YOOBIC Public API

A complete YOOBIC Postman Collection is available for download, containing all API endpoints organized by resource groups with pre-configured environments.

Download: YOOBIC Postman Collection

This collection includes:

• All API endpoints organized by resource groups

• Pre-configured environments (sandbox, prod)

• Automatic authentication handling

• Example requests and responses

• Ready-to-use test scripts

Import the collection into Postman to quickly start testing the YOOBIC API endpoints.

Below is a list of recent enhancements/changes to the YOOBIC Public API.

December 29th, 2025

• New automatic public api collections

• Add Bot Messages endpoint.

• Add Chats endpoint.

• Add Upload file on files.

April 10th, 2025

• Add folder_id field on files.

• Add folder_name field on files.

February 16th, 2025

• Error messages now partially obscure usernames when relevant.

January 16th, 2025

• Added support for SCIM.

January 15th, 2025

• Add Communities endpoint.

• Add Community Posts endpoint.

January 1st, 2025

• Add address field on events.

• Add virtual_event_link field on events.

• Add total_users field on events.

November 10th, 2024

• Add expires_in field on login auth.

October 30th, 2024

• Add Export manager users endpoint.

• Add Import manager users endpoint.

• Add position field on users.

• Add department field on users.

• Add division field on users.

• Add company field on users.

• Add hiring_date field on users.

• Add skills field on users.

• Add cover field on users.

• Add description field on users.

August 1st, 2024

• Add trigger_on_every_match field on webhooks.

July 15, 2024

• Add new type for import users json on import endpoint.

June 27, 2024

• Add Bots endpoint.

• Add earned_points field on courses.

• Add duration field on courses.

• Add start_date field on courses.

• Add due_date field on courses.

• Add finished_date field on courses.

April 30, 2024

• Add notify field on campaign Publish.

April 17, 2024

• New rate limit for users endpoint for POST, PATCH and DELETE requests

January 31, 2024

• Add Invite users endpoint.

• Add Export archived users endpoint. The exported file now includes custom fields.

• Add Export archived stores endpoint. The exported file now includes custom fields.

November 3, 2023

• Add Mission-Comments endpoint.

October 23, 2023

• Add da, fi, nb and sv fields on translations.

August 15, 2023

• Add Import Users To Archive on users.

• Add Import Users To Un Archive on users.

• Add Import Stores To Archive on stores.

• Add Import Stores To Un Archive on stores.

July 26, 2023

• Add extra security asymetric encryption for logins.

June 20, 2023

• webhooks change in behavior on sandbox environment.

April 23, 2023

• Add new supported topics to webhooks.

April 18, 2023

• Add Invitees endpoint on events.

March 2, 2023

• Update group_id field on groups.

February 7, 2023

• Add weekly_schedule fields on users.

• Add Shifts endpoint.

December 20, 2022

• Add au, ido and vi fields on translations.

November 23, 2022

• Add images field on news.

• Removed image field on news (deprecated).

October 31, 2022

• Add Roles endpoint.

October 20, 2022

• Add Questions endpoint.

October 13, 2022

• Add Answers endpoint.

September 1, 2022

• Add client_ids field on users.

• Add store_type_names field on users.

June 26, 2022

• Publish a campaign based on its current configured audience.

June 22, 2022

• Add security for webhooks.

• Updated limit to the number of notifications that can be sent at once to 50k.

June 14, 2022

• Add Events endpoint.

February 20, 2022

• Add custom_fields field on visits.

December 21, 2021

• Add Import audience on campaigns.

• Add Import new campaigns from template on campaigns.

• Add Get all archives on users.

• Add Get all archives on stores.

October 27, 2021

• Add active field on campaigns.

• Add archived field on campaigns.

September 9, 2021

• Add jobs fields' detail.

• Updated the location of the file containing the errors to be under error.

August 15, 2021

• Errors during an import job are now described in a file and returned as a download_url under errors in the job response.

May 12, 2021

• Add create question on campaigns.

• Add update question on campaigns.

• Add delete question on campaigns.

• Add partial u pdate on campaigns.

May 10, 2021

• Add get and update a missions tasks.

April 7, 2021

• Add ability to get the missions' answers missions.

March 16, 2021

• Add out_of_stock field on products.

March 1, 2021

• Add Password History method for users

January 17, 2021

• Add terms_of_acceptance_date field on users.

• Add tenants

January 13, 2021

• Add vq_fields object in stores description and endpoints to support virtual queuing

January 12, 2021

• Add webhooks endpoint.

December 28, 2020

• Add custom-model-instances

December 7, 2020

• Add task_number field on missions endpoint.

November 19, 2020

• Add capacity field on stores endpoint.

• Add last_seen field on users.

• Add mobile_version field on users.

• Add desktop_version field on users.

November 10, 2020

• Add group_ids field on inventory.

October 26, 2020

• Add unarchive method for stores

• Add unarchive method for users

October 22, 2020

• Add archive method for stores

• Add archive method for users

October 14, 2020

• Add allow_local_login field on users.

September 14, 2020

• Add tags field on news.

• Add POST, DELETE and PATCH endpoints for news.

September 10, 2020

• Add client_role_extension field on users.

August 19, 2020

• Add action_plan_progress field on missions table.

July 23, 2020

• Add available-slots method on waitlist-yoobic-visits endpoint.

• Update waitlist-yoobic-visits response to return store client_id and store title on waitlist-yoobic-visits endpoints.

July 05, 2020

• Add waitlist-yoobic-visits

June 28, 2020

• Add waitlist-customers

May 18, 2020

• Add BOOST endpoint (incentives-kpi)

May 11, 2020

• Add timezone field on stores endpoint.

May 5, 2020

• Add page_titles field on campaigns endpoint.

April 16, 2020

• Add delete method for campaigns

February 19, 2020

• Add to campaigns publish the ability to provide default answers.

February 13, 2020

• Add assign method for plans

February 5, 2020

• Add timezone field on stores endpoint.

February 4, 2020

• Add create method for visits

• Add import method for visits

January 28, 2020

• Add properties on campaigns publish

November 5, 2019

• Add create method for campaigns endpoint.

• Add create method for photos endpoint.

October 2, 2019

• Add store_id field on visit.

• Add user_id field on visit.

• Add creator_id field on visit.

September 5, 2019

• Add visit endpoint.

September 3, 2019

• Add group_ids field on notifications.

August 8, 2019

• Add inventory endpoint.

August 5, 2019

• Add scoring field on campaigns.

• Add recurring field on campaigns.

• Add body field on notifications.

• Add user_ids field on notifications.

• Add badge_type field on notifications.

• Add manufacturer field on products.

• Add brand field on products.

• Add category field on products.

• Add images field on products.

July 9, 2019

• Add authorised_viewers field on news.

• Add description field on news.

• Add group_ids field on news.

June 13, 2019

• Add available_on_book field on missions.

• Add available_on_finished field on missions.

June 3, 2019

• Add average_completed_lesson field on plans.

• Add photo field on stores.

• Add address field on users.

May 16, 2019

• Add duration field on missions.

• Add duration field on lessons.

May 8, 2019

• Add markup_url field on photos.

April 30, 2019

• Add catalog_title field on products.

Mar 24, 2019

• Add vip field on stores.

Mar 11, 2019

• Remove support for the replace (PUT) resource, in favor of partial update (PATCH).

Mar 6, 2019

• Document Current User API

• Document company name restriction on Groups create and import

Feb 25, 2019

• Add endpoint to get a store's Health Score

• Add BOOST endpoints (plans, courses, lessons)

API Resources Overview

Resource	GET	POST	PATCH	DELETE	IMPORT	EXPORT	COUNT
auth		x
answers	x					x	x
badges	x					x	x
bots	x					x	x
bot-messages						x
campaigns	x	x	x	x		x	x
catalogs	x	x	x	x	x	x	x
chats		x
comments	x					x	x
communities	x	x	x			x	x
community-posts	x	x			x	x	x
competencies	x					x	x
course-categories	x					x	x
courses	x					x	x
custom-model-instances					x	x
events	x	x	x	x	x	x	x
files	x	x				x	x
geofilters	x	x	x	x	x	x	x
groups	x	x		x	x	x	x
incentives-kpi	x	x	x	x	x	x	x
inventory	x					x	x
lessons	x					x	x
missions	x		x	x	x	x	x
mission_comments	x	x	x	x	x	x	x
news	x	x	x	x	x	x	x
notifications	x	x				x	x
photos	x	x				x	x
plans	x					x	x
products	x	x	x	x	x	x	x
questions	x					x	x
roles	x					x	x
salesdata	x	x	x	x	x	x	x
shifts	x	x	x	x	x	x	x
store-types	x	x	x	x	x	x	x
stores	x	x	x	x	x	x	x
tenants	x
translations	x	x	x	x	x	x	x
users	x	x	x	x	x	x	x
visits	x	x	x	x	x	x	x
webhooks	x	x	x	x	x	x	x
jobs	x

• API Help - We're here to help!

• API Access - API access authentication

• API Technical Requirements - Technical requirements for communicating with the API - security protocols and rate limits

• API Requests - Formatting of requests sent to the RESTful YOOBIC API

  • Filter - Filter the results using different criteria
    • Order - Ordering the results
    • Paging - Paging through your results
    • Where - Matching your results
    • Fields - including specific fields to your results
  • CRUD Requests - Creating/updating/deleting resources

• API Responses - The common response format of each request

• Asynchronous Jobs - How data is requested asynchronously for endpoints

  • Export file section
  • Import file section

• Endpoint Documentation - Documentation specific for each endpoint. You may also use the links on the table on the sidebar to navigate to any endpoint.

  • Security
  • Answers
  • Badges
  • Bots
  • Bot Messages
  • Campaigns
  • Catalogs
  • Chats
  • Comments
  • Communities
  • Comments
  • Competencies
  • Course-categories
  • Courses
  • Custom-model-instances
  • Events
  • Files
  • Geofilters
  • Groups
  • Incentives Kpi
  • Inventory
  • Lessons
  • Missions
  • Missions
  • News
  • Notifications
  • Photos
  • Plans
  • Products
  • Questions
  • Roles
  • Salesdata
  • SCIM
  • Shifts
  • Store Types
  • Stores
  • Tenants
  • Translations
  • Users
  • Visits
  • Webhooks
  • Jobs

Have questions or need support? Email your YOOBIC Customer Success Manager or support@yoobic.com.

Authentication to the YOOBIC API uses JWT tokens. They are required for accessing API.
JWT tokens are set in the Authorization header for your requests as follows:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

To obtain a valid token you can either:

• Use the auth/login endpoint

• Contact your YOOBIC Customer Success Manager or support@yoobic.com to obtain credentials to use in the /auth/login endpoint.

• Please note that in the case you are using a reverse proxy you must set the parameter proxy_ssl_server_name to on to successfully connect to the prod environment.

Protocol and Communication

• The api is only accessible via HTTPS, using TLS 1.2 or better. We forward secrecy and AES-GCM, and prohibit insecure connections using SSL 3.0 or RC4.

• Environments
  We provide both a Sandbox and a Production environment. Every Friday at 21:55 UTC, Sandbox is refreshed by taking a snapshot of the Production environment. Since this refresh process takes several hours, please avoid using Sandbox during that time. It is available for testing purposes outside of the refresh period.

• Template structure of a request:

  • Base url Production: https://api.yoobic.com/public/api
  • Base url Sandbox: https://api-sandbox.yoobic.com/public/api
  • The <base_url> variable in the example requests is either api.yoobic.com or api-sandbox.yoobic.com.
  • Get all (GET): /{endpoint}?filter={ "where": { "property": "value" }, "skip": 0, "limit": 100, "order": "updated_date DESC", "fields": ["property"] }
  • Count (GET): /{endpoint}?where={ "property": "value" }
  • Create (POST): /{endpoint} should include a valid JSON object as the body.
  • Update (PATCH): /{endpoint}/:id should include a valid JSON object as the body.
  • Delete (DELETE): /{endpoint}/:id

Rate Limits

The API enforces the following rate limits. Exceeding these limits will return the following HTTP error code: 429 Too Many Requests (Rate Limit Exceeded)

• Interval Limit: 10 requests per second (must be in serial, concurrent requests cannot be accepted).
  for the /users endpoint, the limit is 3 requests per second (180 per minute)

• Daily Limit: 100,000 requests per day If you need higher limits to support your specific use case, please contact your YOOBIC Customer Success Manager or support@yoobic.com

Requests for the YOOBIC API are all RESTful, with parameters following the endpoint path or in request body. Each request in the documentation is displayed with the appropriate HTTP method and sample parameters. Data may be sent in as parameters or in the request body as JSON. The requests on the YOOBIC API allow for ordering, paging and filtering on a per entity basis.

Filter

A where filter specifies criteria for returning data. We supports the following kind of filters:

• Order filter

• Paging filter

• Where filter

• Fields filter

A filter must be a JSON encoded string ({"something":"value"}).
To do this, simply use the following syntax:

?filter={ Stringified-JSON }

In the JSON all text keys/strings must be enclosed in quotes (").

Important:
When using stringified JSON, you must use an equal sign after ?filter in the query string.
For example:

GET /entity?filter={"where": { "entity_id": 1234 }, "order": "updated_date DESC", "limit": 100, "fields": ["property", "property"] }

Order Filter

An order filter specifies how to sort the results: ascending (ASC) or descending (DESC) based on the specified property.
Order by one property:

{ "order": "property <ASC|DESC>" }

Order by two or more properties:

{ "order": ["property <ASC|DESC>", "property <ASC|DESC>",...] }

Where:

• property is the name of the property (field) to sort by.

• <ASC|DESC> signifies either ASC for ascending order or DESC for descending order.

Important:
By default ordering will be performed according to the updated_date property.
Each endpoint's table, contains information, to the properties ordering could be performed on.

Paging Filter

Paging can be achieved by a combination of limit and skip parameters.

• limit filter limits the number of records returned to the specified number (or less).
  The maximum number of records that could be fetched is 1000.
  For anything above that, you might want to consider using the export endpoint.

      { "limit": 5 }
  

• skip filter omits the specified number of returned records.

      { "skip": 5 } 
  

• If paging.total > paging.limit in the response of a request:

  It is possible to use the skip filter. Here is an example on how to use it with the users endpoint:
  https://api-sandbox.yoobic.com/public/api/users?filter={"skip": 1000}
  The recommended solution is to add a condition to the API script to loop requests if there are too many elements until all of them are returned.
  The condition would monitor that paging.total - paging.limit <= paging.skip in the response of each request, and if not send another request with newSkip = Skip + 1000 after receiving the last one.
  The other way to manage large requests is to use asynchronous requests. For example with Users, it is possible to export a CSV file of all or some users. See the export section for this.

Where Filter

A where filter specifies a set of logical conditions to match, similar to a WHERE clause in a SQL query.

Use the first form below to test equivalence, that is, whether property equals value. Use the second form below for all other conditions.

{ "where": { "property": value } }

{ "where": { "property": { "op" : value } } }

{ "where": { "and|or": [{ "property": { "op" : value } }, { "property": { "op" : value } }] } }

Where:

• property is the name of a property (field) in the model being queried.

• value is a literal value.

• op is one of the operators listed below.

Operator	Description
gt, gte	Numerical greater than (>); greater than or equal (>=). Valid only for numerical and date values.
lt, lte	Numerical less than (<); less than or equal (<=). Valid only for numerical and date values.
between	True if the value is between the two specified values: greater than or equal to first value and less than or equal to second value.
inq, nin	In / not in an array of values.
neq	Not equal (!=)

Fields Filter

A fields filter specifies properties (fields) to include from the results.

{ "fields": ["property", "property", ...] }

Where:

• property is the name of the proeprty (field) to include.

By default, queries return all properties in results. However, if you specify at least one fields filter, then by default the query will include only those you specifically include with filters.

Important:
The export resource for all endpoints does not allow the fields filter.

Create, update and delete requests follow standard RESTful practices. While some fields are available on a resource, you may not be able to set values for readonly fields such as created_date during a CREATE, UPDATE or DELETE action (it would just be ignored). The allowed parameters are listed at the beginning of each CRUD section for a particular resource.

The Response format varies depending on the type of request:

• Single API requests - simple hash, whether it be an error or not.

• Multiple API requests - a hash containing two lists

  • data for successfull requests.
  • error for failed requests.

The two correspond to the order in the request.

{
     "data": [],
     "error": []
}

For find requests an error or data with an additional paging hash -

{
    "data": [],
    "error": [],
    "paging": {
          "skip": 0,
          "limit": 1000,
          "total": 10000,
    }
}

• skip - The currently requested page. Defaults to 0 if no page is given in the request.

• limit - The maximum amount of records that may be returned in this response. If not given in the filter parameter, defaults to 1000.

• total - The total records that match this request, regardless of current paging results.

Response Headers

• content-type: application/json; charset=utf-8

• status: 200 OK

• ratelimit-limit: 1200

• ratelimit-remaining: 1137

• ratelimit-reset: 1415984218

Multiple Response Body

Description Of Usual Server Responses:

• 200 OK - the request was successful (some API calls may return 201 instead).

• 201 Created - the request was successful and a resource was created.

• 204 No Content - the request was successful but there is no representation to return (i.e. the response is empty).

• 400 Bad Request - the request could not be understood or was missing required parameters.

• 401 Unauthorized - authentication failed or user doesn't have permissions for requested operation.

• 403 Forbidden - access denied.

• 404 Not Found - resource was not found.

• 405 Method Not Allowed - requested method is not supported for resource.

• 429 Too Many Requests - rate limit exceeded.

• 501 Not Implemented - the server lacks the ability to fulfill the request. Usually this implies future availability.

There are 2 endpoints for async jobs

• /import: Import a csv/excel file

• /export: Export data as a csv/excel file

By default, all requests to the External API are synchronous and all data requested are returned within the same request/response cycle. One limitation of this approach is that all responses are limited to a maximum number of records as defined in the Paging section. To enable returning an unlimited number of records, you are able to create a job to be executed asynchronously to return all records that match your current query.

Async Jobs

• GET entity/export

• POST entity/import

Given the following request to get the stores:

https://api.yoobic.com/public/api/stores

It can be converted into an asynchronous job:

https://api.yoobic.com/public/api/stores/export?type=csv

Response Structure and Return Codes

When an asynchronous job is successfully created, a code of 200 will be returned. Any errors will result in a return code of 400 and error messages will be returned in the standard format.

The response structure of a requested asynchronous job includes a job_id that you use on the Jobs endpoint to query for the current status of the endpoint. This structure is almost identical to what is returned from the Jobs endpoint. Please refer to that endpoint for more details about obtaining the status of your job.

{
  "name": "Export csv",
  "type": "normal",
  "priority": 0,
  "nextRunAt": "2018-09-11T15:37:23.088Z",
  "_id": "5b97e133952d1c8776c9e723"
}

Export File Format

The file formats supported for exporting all records via an asynchronous job are CSV or Excel (xlsx). Once a job is completed, the response body of the Jobs endpoint request will return the download_url key that is the URL of the CSV or Excel. For example, the above request will result in a file containing example data delimited by the default delimiter, with headers as follows:

{
  "job_id": "5b97e133952d1c8776c9e723",
  "name": "Export file",
  "data": {
    "authorization": "",
    "input": {
      "filter": null,
      "type": "csv",
      "modelName": "stores"
    },
    "output": {
      "errors": [],
      "data": {
          "download_url": "https://s3.eu-west-1.amazonaws.com/yoobic.transient-file-storage/stores_6b97e133952d1c8776c9e723.csv"
        }
    },
    "stats": {
      "execution_time_milliseconds": 556.81776,
      "execution_time": "556.81776 ms",
      "errors": 0,
      "success": 1
    }
  },
  "progress": 1,
  "lastFinishedAt": "2018-09-11T15:37:28.496Z"
}

• Response "data.input" object The input parameters when creating the job.

• Response "data.output.data" object.
  The data object in the results hash may be either a hash or an array, depending on the endpoint action.

• Response "data.output.errors" hash.
  The errors array only appears in results to inform the client of errors such as incorrect field formats, model validation errors or server errors.

• Response "data.stats" hash.
  The stats object informs about the total execution time and number of errors and/or successes.

Resulting CSV example:

    id; title; address; latitude; longitude; client_id; store_type_id; store_type_name; created_date; updated_date
    5b97e017952d1c8776c9e71e; Home; Statue of Liberty, New York, USA; 40.6895453; -74.0449292; 001; 5b97e00411ec54f2e3a0936e; TEST; 2018-09-11T15:32:39.607Z; 2018-09-11T15:32:39.607Z

Resulting Excel example:

In case of a request to export an excel file https://api.yoobic.com/public/api/stores/export?type=excel it would result in:

Export File Expiration

Currently all exports are set to expire one day after they are created at which point they will be inaccessible.

Import File

Import a CSV/Excel file.
This action is asynchronous and returns the id of a job. See jobs endpoint to query the status of the job. Make sure that you make a multipart/form-data query, passing the CSV/Excel file as named parameter file. When you create a CSV/Excel file to import, you'll probably generate this list from some other information management system or database. Most of these systems have some facility for creating a CSV/Excel export file. If you need to create the list from scratch you can use a program like Microsoft Excel or OpenOffice.org Calc.

Important:

• To ensure correct handling of special characters, you must generate the CSV/Excel file using the UTF-8 character encoding.

• The first row of the file is the header row, and you must include it in the file.

• The header row must contain any required fields in the table below, plus any other fields listed in the table below that you want to include.

• Empty columns of data in the file will overwrite any existing data for that entity (empty column is treated as a null value).

• For Excel files, array type fields (i.e.: tags for users or stores, client_ids for users…) must be comma separated string i.e.: Tag1,Tag2,Tag3 or Tag1, Tag2, Tag3

• For CSV files, array type fields can be either comma separated strings (i.e.: Tag1,Tag2,Tag3 or Tag1, Tag2, Tag3) or JSON array with quotes (i.e.: "["Tag1","Tag2","Tag3"]")- In Addition for CSV the field separator is ; and line separator is line-break.

• Make sure there are no duplicates by the defined primary keys as there is no guarantee on the order in which the import iterates over the rows.

• Date values should comply with the ISO format, i.e. 2019-12-31 or 2019-12-31T23:59:59:999.

• Escape special characters in CSV files with double quotes, for example: "<a href=""https://example.com"">Link</a>".

This endpoint exposes the login method in order to create a valid access token for subsequents call to the API, as well as an endpoint for invalidating the current access token. The latter will have the effect of requiring anyone currently using the existing token to login again in order to get the new one.

Answers are the users’ replies to the questions raised by their colleagues in the Questions menu. Other users can vote for answers they think are best, like them, and a user with the right permission can also validate an answer to indicate it is the right or best one.

Fields

Field	Type	Required	Readonly	OrderBy	Description
answer_id	string	x	x		Unique id of the answer
question_id	string		x		Reference to the question
user_id	string		x		User id answering this question
text	string		x		The answer
image	string		x		The url to the image
is_verified	boolean		x		Whether or not this is a verified answer
user_verified	string		x		User id verifying this answer
likes	number		x		Likes count
created_date	date		x		Creation date
updated_date	date		x	x	Last update date

A badge is a customized reward earned by a learner after completing a lesson.

Fields

Field	Type	Required	Readonly	OrderBy	Description
badge_id	string	x	x		Unique id of the badge
creator_id	string		x		Unique id of the badge creator
title	string		x		Badge title
icon	string		x		Badge icon name
created_date	date		x		Creation date
updated_date	date		x	x	Last update date

This API is exclusively used to handle bots external to YOOBIC. External bots are an AI feature of the YOOBIC chat that enhances user interactions by automating workflows and streamlining processes to boost efficiency. By using third party bot APIs on top of the YOOBIC NEO chatbots, we enable users to access an unlimited number of specialised bots for back-office automations, HR, IT help, and more.

Fields

Field	Type	Required	Readonly	OrderBy	Description
bot_id	string		x		Unique id of the bot
creator_id	string		x		Unique id of the badge creator
name	string				Bot name
is_active	boolean				Enable or disable this bot (default: true)
webhook_url	string				Unique http target url to the bot
created_date	date		x		Creation date
updated_date	date		x	x	Last update date

Bot analytics allow you to improve your bots by understanding how your teams use them and how satisfied they are with the answers. The key metrics available can be used to monitor the usage of the feature and to analyze frequent questions where knowledge is lacking in order to create new content and add it to the NEO Chatbot sources.

Fields

Field	Type	Required	Readonly	OrderBy	Description
bot_id	string		x		Unique id of the bot
bot_message_id	string		x		Unique if of the message sent to the bot
user_id	string		x		Unique id of the user that sent the question
username	string		x		Username of the user that sent the question
question	string		x		Question of the user
answer	string		x		Answer of the bot to the question of the user
feedback	boolean		x		True if the user put a ‘thumbs up’ and false if the user put a ‘thumbs down' on the answer of the bot
answered	boolean		x		True if the question was answered and false if it wasn’t (equivalent to ‘I don’t know' response from the bot')
created_date	date		x		Created Date
updated_date	date		x		Updated Date

Business KPIs data allows integration of external business data per location. This is the data that will be used to display Business KPIs in the Activity Hub or Today's focus widget of the application.

Periods can be: yearly, monthly, weekly, or daily.

Salesdata uniqueness is determined by:

• store_id

• reporting_date

• title

• category

• value_frequency

• target

In case a new salesdata is created with values for the latter five which already exist in a salesdata, then the salesdata will be updated. Otherwise, a new salesdata entry will be created

The category parameter refers to which KPI will use this data point to calculate the value in the app. For example, the 5 predefined KPIs are based on the following categories:

• sales for the Sales KPI, calculated as the Sum of all sales data in the KPI's frequency

• sales and transactions for the Average Basket KPI, calculated as SUM(sales) / SUM(transactions) in the KPI's frequency

• items and transactions for the UPT KPI, calculated as SUM(items) / SUM(transactions) in the KPI's frequency

• transactions and traffic for the Conversion rate KPI, calculated as SUM(transactions) / SUM(traffic) in the KPI's frequency

• reviews for the Reviews, calculated as AVG(reviews) in the KPI's frequency

• For Custom KPIs, the category must match the category defined in the Business KPI configuration menu.

Reporting Date

• The reporting_date must correspond to the expected calculation period of the KPI.

• Example: For daily sales data, push one entry per store each day (e.g., timestamp at store closing time).

Targets

• Define a target with the parameter target: true.

• The reporting_date should correspond to the target's period.

  • For weekly targets, use the timestamp for the start of the week.

Fields

Field	Type	Required	Readonly	OrderBy	Description
salesdata_id	string		x		Unique id of the salesdata
store_id	string			x	Unique id of the store
store_client_id	string				client_id of the store. Can be used instead of the store_id
reporting_date	date	x			Reporting date
title	string	x		x	The salesdata report title
category	string	x		x	Salesdata name
value	number	x			Salesdata value
value_currency	string				Salesdata currency
value_frequency	string	x			The product measuring frequency : yearly / monthly / weekly / daily / hourly
target	boolean				Indicates if the associated value is a target
created_date	date		x		Creation date
updated_date	date		x	x	Last update date

Either store_id or store_client_id can be used.