Download OpenAPI specification:Download
The Data API gives you access to your data on the Virtual Shopping platform. You will find one endpoint per type of data.
We will continuously expand this API. Make sure your code can handle new JSON properties and does not depend on the order in which JSON objects are returned by the API.
Breaking changes will be introduced under new version paths (/v2) and older versions will become deprecated after a specific schedule that will be communicated to you.
Once you request access via your CSM, we will send you credentials securely. You will need to follow the OAuth flow to receive an access token in order to make API calls.
Once your access has been generated, you will receive the following information: client id, client secret and client audience. Using OAuth, you will be able to request an access token using your credentials and use it to call the Data API endpoints.
Request an access token (JWT) using OAuth. Make sure to use the correct server URL for the correct region and environment.
| client_id | string Client ID |
| client_secret | string Client Secret |
| audience | string Enum: "https://eu-data.api.usehero.com" "https://us-data.api.usehero.com" "https://eu-data.api.preprod.usehero.com" "https://us-data.api.preprod.usehero.com" Static value defining the API that will be called |
| grant_type | string Value: "client_credentials" Static value to be set to "client_credentials" |
| access_token | string Access token to use in API calls (Authorization header) |
| expires_in | number |
| token_type | string Value: "Bearer" |
| error | string Value: "access_denied" |
| error_description | string Value: "Unauthorized" |
{- "client_id": "string",
- "client_secret": "string",
- "grant_type": "client_credentials"
}{- "access_token": "string",
- "expires_in": 0,
- "token_type": "Bearer"
}The Data API gives you access to your data on the Virtual Shopping platform. You will find one endpoint per type of data. Each endpoint has its own query parameters to filter the data and will return a schema based on the data structure.
Please note that you should select the correct server URL for your region and environment. The URL is different from the authentication endpoint.
Query associates records
| fromDate required | string <date-time> Filtering associates that have been updated after that date. Date and time in the following ISO format: 2021-03-15T12:34:00Z |
| available | boolean Filter available associates only. |
| id | string Associate IDs (one or more separated by a comma) |
| nextToken | string Include the token from a previous query to load the next page of result |
| success | boolean |
Array of objects (Associate) [ items ] | |
| nextToken | string or null |
curl \ --request GET \ --url 'https://eu-data.api.usehero.com/v1/data/associates?fromDate=1997-04-13T13:12:55.763Z' \ --header 'Authorization: Bearer your-access-token-here'
{- "success": true,
- "results": [
- {
- "_id": "string",
- "approvalStatus": "string",
- "email": "string",
- "firstName": "string",
- "lastName": "string",
- "available": true,
- "busy": true,
- "_created_at": "2019-08-24T14:15:22Z",
- "spokenLanguages": [
- "string"
], - "storeName": "string",
- "storeId": "string",
- "employeeId": "string"
}
], - "nextToken": "string"
}Query shoppers records
| fromDate required | string <date-time> Filtering shoppers that have been updated after that date. Date and time in the following ISO format: 2021-03-15T12:34:00Z |
| id | string Shopper IDs (one or more separated by a comma) |
| nextToken | string Include the token from a previous query to load the next page of result |
| success | boolean |
Array of objects (Shopper) [ items ] | |
| nextToken | string or null |
curl \ --request GET \ --url 'https://eu-data.api.usehero.com/v1/data/shoppers?fromDate=1997-04-13T13:12:55.763Z' \ --header 'Authorization: Bearer your-access-token-here'
{- "success": true,
- "results": [
- {
- "_id": "string",
- "location": [
- 0,
- 0
], - "_created_at": "2019-08-24T14:15:22Z",
- "firstName": "string",
- "shopperName": "string",
- "lastOnlineTime": "2019-08-24T14:15:22Z",
- "userAgent": "string",
- "username": "string",
- "visitor": "string",
- "contactEmail": "string",
- "contactPhone": "string",
- "crm": { },
- "usedChatFeature": true
}
], - "nextToken": "string"
}Query contacts records
| fromDate required | string <date-time> Filtering contacts that have been updated after that date. Date and time in the following ISO format: 2021-03-15T12:34:00Z |
| id | string Contact IDs (one or more separated by a comma) |
| userId | string Shopper ID (only 1 ID supported) |
| associateId | string Associate ID (only 1 ID supported) |
| nextToken | string Include the token from a previous query to load the next page of result |
| success | boolean |
Array of objects (Contact) [ items ] | |
| nextToken | string or null |
curl \ --request GET \ --url 'https://eu-data.api.usehero.com/v1/data/contacts?fromDate=1997-04-13T13:12:55.763Z' \ --header 'Authorization: Bearer your-access-token-here'
{- "success": true,
- "results": [
- {
- "_id": "string",
- "userId": "string",
- "acquisitionDate": "2019-08-24T14:15:22Z",
- "_updated_at": "2019-08-24T14:15:22Z",
- "associateId": "string",
- "firstName": "string",
- "lastName": "string",
- "phoneNumber": "string",
- "email": "string",
- "birthday": "string",
- "state": "default",
- "optInState": "active",
- "notes": [
- {
- "_id": "string",
- "content": "string"
}
]
}
], - "nextToken": "string"
}Query shoppers events
| fromDate required | string <date-time> Filtering events that have been created after that date. Date and time in the following ISO format: 2021-03-15T12:34:00Z |
| toDate | string <date-time> Filtering events that have been created before that date. Date and time in the following ISO format: 2021-03-15T12:34:00Z |
| type | string Enum: "user-product-view" "user-basket-checkout" "user-basket-add" "user-basket-delete" "user-search" "user-category-view" Event type |
| userId | string Shopper IDs (one or more separated by a comma) |
| attributedAssociate | string Associate ID who has been attributed the event (only applicable to user-basket-checkout events) |
| nextToken | string Include the token from a previous query to load the next page of result |
| success | boolean |
Array of objects (ShopperEvent) [ items ] | |
| nextToken | string or null |
curl \ --request GET \ --url 'https://eu-data.api.usehero.com/v1/data/shopper-events?fromDate=1997-04-13T13:12:55.763Z' \ --header 'Authorization: Bearer your-access-token-here'
{- "success": true,
- "results": [
- {
- "_id": "string",
- "type": "user-product-view",
- "time": "2019-08-24T14:15:22Z",
- "userId": "string",
- "sessionId": "string",
- "productSku": "string",
- "productQuantity": 0,
- "category": "string",
- "searchTerms": "string",
- "location": "string",
- "lineItems": [
- {
- "productSku": "string",
- "productQuantity": 0
}
], - "attributedAssociate": "string",
- "orderId": "string",
- "subtotal": 0,
- "currency": "string"
}
], - "nextToken": "string"
}Query conversation events
| fromDate required | string <date-time> Filtering events that have been created after that date. Date and time in the following ISO format: 2021-03-15T12:34:00Z |
| toDate | string <date-time> Filtering events that have been created before that date. Date and time in the following ISO format: 2021-03-15T12:34:00Z |
| type | string Enum: "conversation-claimed" "conversation-created" "conversation-restarted" "conversation-archived" "conversation-transfered" "conversation-dropped" "lead-created" "lead-expired" "aborted-live-lead" "getnotified-requested" "conversation-auto-archived" "conversation-auto-archived-store-offline-or-busy" Event type |
| userId | string Shopper IDs (one or more separated by a comma) |
| associateId | string Associate ID linked to the events |
| nextToken | string Include the token from a previous query to load the next page of result |
| success | boolean |
Array of objects (ConversationEvent) [ items ] | |
| nextToken | string or null |
curl \ --request GET \ --url 'https://eu-data.api.usehero.com/v1/data/conversation-events?fromDate=1997-04-13T13:12:55.763Z' \ --header 'Authorization: Bearer your-access-token-here'
{- "success": true,
- "results": [
- {
- "_id": "string",
- "type": "conversation-claimed",
- "time": "2019-08-24T14:15:22Z",
- "userId": "string",
- "departmentId": "string",
- "sessionId": "string",
- "conversationId": "string",
- "partId": "string",
- "associateId": "string",
- "currentChannel": "string",
- "lead": true,
- "location": "string",
- "customerLocation": [
- 0,
- 0
], - "needId": "string",
- "customerService": true,
- "fromAssociate": "string",
- "leadContactType": "string"
}
], - "nextToken": "string"
}Query contact events
| fromDate required | string <date-time> Filtering events that have been created after that date. Date and time in the following ISO format: 2021-03-15T12:34:00Z |
| toDate | string <date-time> Filtering events that have been created before that date. Date and time in the following ISO format: 2021-03-15T12:34:00Z |
| type | string Enum: "customer-invited" "contact-added" "contact-initial-optedin" "contact-optedout" "contact-optedin" "contact-reassigned" "contact-hidden" "contact-unhidden" "contact-optin-state-update" "contact-message-sent" Event type |
| userId | string Shopper IDs (one or more separated by a comma) |
| contactId | string Contact IDs (one or more separated by a comma) |
| associateId | string Associate ID linked to the events |
| nextToken | string Include the token from a previous query to load the next page of result |
| success | boolean |
Array of objects (ContactEvent) [ items ] | |
| nextToken | string or null |
curl \ --request GET \ --url 'https://eu-data.api.usehero.com/v1/data/contact-events?fromDate=1997-04-13T13:12:55.763Z' \ --header 'Authorization: Bearer your-access-token-here'
{- "success": true,
- "results": [
- {
- "_id": "string",
- "type": "customer-invited",
- "time": "2019-08-24T14:15:22Z",
- "userId": "string",
- "sessionId": "string",
- "conversationId": "string",
- "associateId": "string",
- "contactId": "string"
}
], - "nextToken": "string"
}