Every API request returns header contains the following fields: RateLimit-Limit: your_limit_quota_of_endpoint
RateLimit-Remaining: remaining_requests_until_reset
RateLimit-Reset: next_reset_time
Retry-After: next_reset_time(only available when status code is 429)
- name: Tutorials description: "# Get Reporting Data via API\n\n\n## Introduction\n\nThis short tutorial shows you how to use the Holistics APIs to get report data in raw tabular form (CSV, Excel).\n\nThis tutorial uses Ruby, but you can easily use any other language for it.\n\n> ⓘ **INFO**\n>\n> We'll be working on client libraries wrapper around our API. Once done, using the APIs will be simpler by just making a few function calls.\n\n## Mechanism\n\nSince Holistics uses a async job queuing system to process job, you can't make a single API call to retrieve the results. We need to submit an 'export request', then wait for the export job to finish, and then make an API call to download the results.\n\n\n**API Endpoints used:**\n- [Export a Dashboard Widget](#tag/Dashboard-Widgets/operation/DashboardWidgets_SubmitExport)\n- [Download an exported job](#tag/Exports/operation/Exports_Download)\n\n## Steps\n\nLet's go through the steps here.\n\n### 1. Setting Up API Key\n\nPlease see [guide](/api/index.md) to set up and retrieve your API key.\n\n### 2. Initial code structure\n\nTo make things simple and reusable, we'll wrap our code around a `HolisticsAPI` class. We'll also use the [httprb](https://github.com/httprb/http) gem to handle making HTTP calls.\n\n```ruby\nrequire 'http'\nclass HolisticsAPI\n def initialize(api_key, host: 'secure.holistics.io')\n @api_key = api_key\n @api_url = \"https://#{host}/api/v2\"\n @http = HTTP.headers({'X-Holistics-Key' => @api_key})\n end\nend\n```\n\n### 3. (Optional) Get Filters ID for your Dashboard Export\n\nIf you want to include **Filters** in your export, you will need to get their Filter IDs. Please follow these steps to obtain them:\n\n**1. Get your Dashboard ID**\n\nThe Dashboard ID can be retrieved by looking at its URL in the browser. In this sample URL below, the Dashboard ID would be 16076.\n\n
![](\"https://cdn.holistics.io/docs/dynamic-filter/dashboard.png\"/)
\n\n**2. Get Filter ID**\n\nSupposed that your dashboard has a sets of filters like the one below. Let's get the ID of the **Date filter** to include it in our export.\n\n![](\"https://cdn.holistics.io/docs/dynamic-filter/filters.png\"/)
\n\nWe will use [Get Dashboard API](#operation/Dashboards_Get) for this purpose. Let's call the API with the Dashboard ID from step 1.\n\n```ruby\ncurl --location --request GET 'https://secure.holistics.io/api/v2/dashboards/{your_dashboard_id}' \\\n--header 'X-Holistics-Key: your_API_key' \\\n--header 'Content-Type: application/json' \\\n```\nThe response would be quite lengthy, but you just need to find the **dynamic_filters** field to get the **Filter ID**.\n\n![](\"https://cdn.holistics.io/docs/dynamic-filter/api-response.png\")
\n\nYou can then use this Filter ID in the next step.\n\n\n### 4. Submit widget export request\n\nMake sure you have the DashboardWidget ID in hand. The widget ID can be retrieved by opening up the widget in the dashboard, and look at the `_e` parameter in the URL. For example, 4175 is the widget ID of the below.\n\n```\nhttps://secure.holistics.io/dashboards/v3/12345-some-dashboard/?_e=4175\n```\n> ⓘ **INFO**\n>\n> (Optional) Include filter conditions in your export\n> If you wish to include a filter condition in your export, first refer to [step 3](#3-optional-include-filters-in-your-dashboard-export) to get your desired **Filter ID**.\n>\n> Then, append **dashboard_filter_conditions** in your request body.\n>\n> - **dynamic_filter_id** is the Filter ID from step 3.\n> - **condition:**\n> - **operator:** refer to [Data Modeling Condition](#tag/Data-Modeling/DataModelingCondition) for all available operators.\n> - **values:** is an array of strings or integers that go with the operator.\n>\n> For example, assuming that you have completed step 3, to apply a **Date Filter** that filters data from 2 months ago to the export, simply include this snippet to your request.\n>\n> ```ruby\n> {\n> \"dashboard_filter_conditions\": [\n> {\n> \"dynamic_filter_id\": 2335,\n> \"condition\": {\n> \"operator\": \"matches\",\n> \"values\": [\n> \"2 months ago\"\n> ]\n> }\n> }\n> ]\n> }\n> ```\n\nThen we make the call to submit widget export:\n\n```ruby\nclass HolisticsAPI\n # ...\n\n # output: 'csv' or 'excel'\n def submit_report(widget_id, output: 'csv')\n url = @api_url + \"/dashboard_widgets/\" + widget_id.to_s + \"/submit_export\"\n\n response = @http.post(url, json: {output: output})\n res = JSON.parse(response.to_s)\n\n if response.code == 200\n res['job']['id']\n else\n raise StandardError.new(res['message'])\n end\n end\nend\n\n```\n\nIf successful, this method returns the job ID of the job created.\n\n### 5. Waiting for job to complete\n\nThe job will the go to the queue system waiting to be processed. This method below will continuously poll the job's metadata until it is either success, or failure.\n\n\n```ruby\nclass HolisticsAPI\n # ...\n\n def wait_for_job_status(job_id)\n url = @api_url + \"/jobs/\" + job_id.to_s\n\n while true do\n response = @http.get(url)\n res = JSON.parse(response.to_s)\n\n raise StandardError.new(res['message']) if response.code != 200\n\n status = res['job']['status']\n puts \"===> status: #{status}\"\n\n unless ['created', 'running', 'queued'].include?(status)\n return status\n end\n\n # Wait a while before pinging again\n sleep 2\n end\n end\nend\n```\n\n### 6. Downloading the results\n\nOnce the job finishes, we make one final API call to\n\n```ruby\nclass HolisticsAPI\n # ...\n\n def download_export(job_id)\n url = @api_url + \"/exports/download\"\n response = @http.follow.get(url, params: {job_id: job_id})\n\n raise StandardError.new(JSON.parse(response.to_s['message'])) if response.code != 200\n\n response.to_s\n end\nend\n\n```\n\n### 7. Putting things together\n\nOnce the above class is defined, let's put in a short code to perform all 3 steps to get the data.\n\n\n```ruby\nAPI_KEY = 'your_api_key'\nWIDGET_ID = 1234 # your widget\n\napi = HolisticsAPI.new(API_KEY)\n\njob_id = api.submit_report(WIDGET_ID)\nputs \"===> job_id: #{job_id}\"\n\njob_status = api.wait_for_job_status(job_id)\nputs \"===> job_status: #{job_status}\"\n\nif job_status == 'success'\n csv_data = api.download_export(job_id)\n puts csv_data # your CSV-formatted data here!\nend\n\n```\n\n### 7. Profit!\n\nSave the data into CSV, convert them into array, or feed them to other applications. The potentials are limitless!\n\n\n# Create Data Alerts using API\n\n## Introduction\n\n---\n\nIn Holistics, you can set up a system that sends you automatic notifications when data meets certain criteria, allowing you to make timely and strategic business decisions. This concept is called as **Data Alert.** \n\nHolistics offers a\_[set of public API endpoints](#tag/Data-Alerts)\_allowing clients to work with Data Alert. This tutorial shows you how to programmatically create these data alerts using the API.\n\n## The Use case\n\n---\n\nAssuming you are an e-commerce company that wants to track the number and status of orders placed on your platform. You can set up data alerts that trigger notifications when certain conditions are met, such as:\n\n1. **A number of orders placed in a specific time period exceed a certain threshold.**\n2. **A certain percentage of orders are canceled or marked as \"canceled\".**\n\nYou can receive these alerts through email or slack, and they can use this information to quickly respond to any issues or to make informed decisions about adjusting inventory or shipping processes.\n\nLet's walk through how we can create a data alert to **track your number of orders using Holistics API**.\n\n## High-level Approach\n\n---\n\nWe will use the API to create email data alerts. Specifically, we'll send a POST request to\_[Holistics create data alert API](#operation/DataAlerts_Create).\n\nBefore that, we need to prepare the following:\n\n- A dashboard widget with relevant report\n- Holistics API Key: We need to setup the API key. Refer to\_[this guide](#section/Authentication)\_for more info.\n\n## How to create a data alert via API\n\n---\n\n### Step **1. Preparing the dashboard widget**\n\nYou will need to create a dashboard widget containing the data of interest to you. In this example, I used this simple report that counts the total number of orders.\n\n\n\n### Step 2: Making the API Call\n\nWe'll be using the following [endpoint](#tag/Data-Alerts/operation/DataAlerts_Create):\n\n```jsx\nPOST https://secure.holistics.io/api/v2/data_alerts\n```\n\nThere are some notable configuration options in this request:\n\n- `schedule`: Specify how frequently the email schedule should be\n- `viz_conditions`: Specify what alert condition should be check on the report result. By configuring this, we can customize the alert for each alerting use case.\n- `dest`: Specify configurations regarding the alert delivery destination, e.g. the recipients' information.\n- `dynamic_filter_presets`: Specify what dynamic filters should be applied to the report. By configuring this, we can customize the report for each recipient.\n\nBelow is a sample request body. Refer to\_[Holistics API docs](#tag/Data-Alerts/operation/DataAlerts_Create)\_for more information on these fields.\n\n\n\n#### Dest field\n\n- `dest`: Specify configurations regarding recipients' information\n - `title`\_(string): Note that Holistics support\_[dynamic variables](https://docs.holistics.io/docs/delivery/email-schedules#dynamic-variables-support)\_in email title. For example, the title\_`Sales report for {{$today}}`\_sent on 29/09/2021 will be rendered as\_`Sales report for 2021-09-29 Wed`.\n - `type`: This tells Holistics you want to receive notification via email: `EmailDest` or Slack: `SlackDest`\n - If you choose `SlackDest`, you will need to [get the id and the name of your slack channel](https://help.socialintents.com/article/148-how-to-find-your-slack-team-id-and-slack-channel-id#:~:text=the%20Team%20ID.-,Open%20any%20web%20browser%20and%20log%20in%20to%20your%20Slack,represents%20your%20Slack%20Channel%20ID.) for the `slack_channels` field\n\n#### Viz conditions\n\n- `viz_conditions`: Coming to the core of the alert, the condition to set data alert\n - `field_path`: This is used to extract from a specific data model\n - `field_name`: field name of the field in the data model you want to apply the condition.\n - `model_id`: The id of the data model associated with the `field_name`\n - You can get the `field_name` and `model_id` by following these steps\n - From the widget id → [Get a dashboard widget](#tag/Dashboard-Widgets/operation/DashboardWidgets_Get) (include_report=true) then extract `query_report.viz_settings.fields`, you can find the field you want to add condition then extract path`_hash` to get `model_id` and `field_name`\n - `aggregation`: The aggregation that will be applied on the field when processing the condition.\n - `transformation`: The transformation that will be applied on the field when processing the condition.\n - `condition`: be applied on the Data Modeling layer to filter your data. Check out our document [here](#tag/Data-Modeling/DataModelingCondition) for more details.\n - Example: you have a field `id` and want to check whether the number of it is greater than 35000\n\n ```json\n {\n \"field_path\": {\n \"field_name\": \"id\",\n \"model_id\": 1\n },\n \"aggregation\": \"count\",\n \"transformation\": null,\n \"condition\": {\n \"operator\": \"greater_than\",\n \"modifier\": null,\n \"values\": [35000],\n },\n }\n\n ```\n\n\n#### Schedule\n\n`schedule`:\_This field is used to specify the schedule for your email schedule.\n\n`repeat`\_(string): You will need to input a\_[crontab expression](https://crontab.guru/) to let Holistics know how frequently you want your email schedule to run.\n\n#### Dashboard Filters\n\n`dynamic-filter-presets`\_is where you define your filter presets.\n\n`dynamic_filter_id`: To get your\_`filter_id`, send a request to\_[Dashboards#Get API](#operation/Dashboards_Get)\_to get the dashboard info.\n\n`preset_conditions`: Let's go through our example to better illustrate this field.\n\nWe want to set a value for the filter by setting a preset condition.\_**A preset condition consists of an operator and a list of values.**\_Holistics supports various operators and provides several examples\_[here](#tag/Data-Modeling/DataModelingCondition).\n\nIn this case, we want to use operator\_`is`\_and set values to\_`customer_id`. By this, we mean the filter's default value equals exactly to\_`customer_id`.\n\nFinally, we also want to set up another dynamic filter preset to filter data to the whole of last week. Fortunately, Holistics allows a list of dynamic filter presets. For the Date Range filter, we similarly want to use operator\_`is`\_and set values to\_`\"last 7 days\"`.\n\nOur final\_`dynamic_filter_presets`\_object will look like this.\n\n```js\ndynamic_filter_presets = [\n {\n \"dynamic_filter_id\": MY_CUSTOMER_FILTER_ID,\n \"preset_condition\": {\n \"operator\": \"is\",\n \"values\": [\n customer_id\n ]\n }\n },\n {\n \"dynamic_filter_id\": MY_DATE_RANGE_FILTER_ID,\n \"preset_condition\": {\n \"operator\": \"is\",\n \"values\": [\n \"last 7 days\"\n ]\n }\n }\n]\n\n```\n\n\n### **Step 3: Verify to see if your data alert is created[](https://docs.holistics.io/api/v2/create-data-schedule#step-3-double-check-to-see-if-your-email-schedule-is-created)**\n\nThe request should now be ready. After sending it to Holistics, the server will respond with a\_[HTTP status response code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)\_to indicate whether the request was successful / failed.\n\nLastly, be sure to head over to the Holistics page to see if your data alert is created.\n\n\n\n### **Example script[](https://docs.holistics.io/api/v2/create-data-schedule#example-script)**\n\n---\n\nAn example script to send requests written in Ruby is available here:\n\n```ruby\n# install the neccessary dependencies for this script to work\nrequire \"bundler/inline\"\nrequire \"net/http\"\nrequire \"json\"\n\ngemfile do\n source \"https://rubygems.org\"\n gem \"net-http\"\nend\n\n# this the Holisitics API endpoint that we need to send our POST request to\nDATA_ALERT_ENDPOINT = URI(\"https://secure.holistics.io/api/v2/data_alerts\")\n\n# Step 1: Create a POST request to the endpoint below\nrequest = Net::HTTP::Post.new(DATA_ALERT_ENDPOINT)\n\n# Step 2: Provide your authentication information\nrequest[\"X-Holistics-Key\"] = \"mysecretAPIkey\"\n\n# Step 2.1: This line helps the system know that we are sending a JSON request\nrequest.content_type = \"application/json\"\n\n# Step 3: Provide information for your data alert in the request body\nrequest.body = {\n \"data_alert\": {\n \"title\": \"Tracking number of orders\",\n \"source_id\": 41,\n \"source_type\": \"DashboardWidget\",\n # Conditions for the Alert to be Triggered\n \"viz_conditions\": [\n {\n \"field_path\": {\n \"field_name\": \"id\",\n \"model_id\": 12\n },\n \"aggregation\": \"count\",\n \"transformation\": null,\n \"condition\": {\n \"operator\": \"greater_than\",\n \"modifier\": null,\n \"values\": [35000]\n }\n }\n ],\n # Destination for the Alert\n \"dest\": {\n \"type\": \"EmailDest\",\n \"title\": \"The number of orders has just exceeded than 35000\",\n \"recipients\": [\n \"admin@domain.com\"\n ],\n \"options\": {\n \"body_text\": null\n }\n },\n # Schedule for the Alert to be Triggered\n \"schedule\": {\n # Repeat Everyday at 7:00 AM\n \"repeat\": \"0 7 * * *\",\n \"paused\": false\n },\n # Dynamic Filter Presets for the Alert\n \"dynamic_filter_presets\": [\n {\n \"preset_condition\": {\n \"operator\": \"is\",\n \"modifier\": null,\n \"values\": [\"VN\", \"SG\"],\n },\n \"dynamic_filter_id\": 1\n },\n {\n \"preset_condition\": {\n \"operator\": \"is\",\n \"modifier\": null,\n \"values\": [\n \"Male\"\n ],\n },\n \"dynamic_filter_id\": 2\n }\n ]\n }\n}.to_json\n\n# Step 4: Send the request to Holistics!\nresponse = Net::HTTP.start(\n DATA_ALERT_ENDPOINT.hostname,\n DATA_ALERT_ENDPOINT.port,\n :use_ssl => DATA_ALERT_ENDPOINT.scheme == \"https\",\n) do |https|\n https.request(request)\nend\n\n# Optional: Output the result into the terminal\nputs [response.code,response.message].join(' ')\n```\n\n# Create Email Schedules using API\n\n## Introduction\n\nIn Holistics, you can set up schedules sending reports or dashboards to a group of recipients via email, Slack, SFTP, or Azure Blob. This concept is called **Data Schedule**.\n\nHolistics offers a [set of public API endpoints](#tag/Data-Schedules) allowing clients to work with Data Schedule. This tutorial shows you how to use the API to create these data schedules programmatically.\n\n## The Use Case\n\nSuppose you are a B2B SaaS company that has a feature to email usage statistics to your customers every week. You want to set it up such that:\n\n- When a new customer onboards to your platform, you want **Holistics to send a weekly email report** to that customer.\n- The weekly email reports **should be customised to display information regarding the usage data of that customer only**\n\nLet's walk through how we can solve this problem using Holistics API.\n\n\n## High-level Approach\n\nWe will use the API to create email reports. Specifically, we'll send a POST request to [Holistics' create email schedule API](#operation/DataSchedules_Create).\n\nBefore that, we need to prepare the following:\n\n- A dashboard with relevant reports. This dashboard will be emailed to the customer.\n- The dashboard should have a \"Customer\" filter to filter down the data for a particular customer.\n- Holistics API Key: We need to setup the API key. Refer to [this guide](#section/Authentication) for info.\n\n## Step 1: Preparing the Dashboard\n\nYou will need to create a master dashboard that contains the reports you want to send to the customers. In this example, we have a `Customer Usage Data` dashboard which showcases the statistics of jobs that Holistics customers execute in our platform. We also have two filters in this dashboard, `Date Range` and `Customer`. \n\n- The **Customer ID filter** accepts a customer ID, then passes it to the report within the dashboard. The report then replaces the ID with its placeholder in a prepared SQL query, reruns the query, and fetches only data that belongs to that customer. In other words, this filter helps **filter down to the usage data of that customer only**.\n- Similarly, the **Date Range filter**'s value accepts `\"last 7 days\"`, `\"last 14 days\"`, `\"last 30 days\"`, or `\"any time\"`. This filter helps **filter usage data by a date range**. Note that this filter can be optional.\n\nIf you are not sure on how to create dashboards and filters, refer to [Dashboard Docs](https://docs.holistics.io/docs/dashboards).\n\n\n\n\n## Step 2: Making the API Call\n\nWe'll be using the following [endpoint](#operation/DataSchedules_Create):\n\n```jsx\nPOST https://secure.holistics.io/api/v2/data_schedules\n```\n\nThere are some notable configuration options in this request:\n\n- `schedule`: Specify how frequent the email schedule should be\n- `dynamic_filter_presets`: Specify what dynamic filters should be applied to the reports. By configuring this, we can customise the report for each recipient.\n- `dest`: Specify configurations regarding recipients' information.\n - Remember to set `dest.type` to \"EmailDest\"\n\nBelow is a sample request body. Refer to [Holistics API docs](#operation/DataSchedules_Create) for more information on these fields.\n\n\n\n> ⓘ **INFO**\n>\n> 💡 Most of the fields are straightforward which means that you can fill them out by reading our API docs. Refer to this section below for notes on trickier fields.\n\n\n### Common fields\n\n- `id` (integer): This is used to uniquely identified your object. Holistics automatically generates an id for you if you don't specify this.\n- `source_id` (integer): This tells Holistics which dashboard you want to send email to. To determine this value, view your dashboard link. For example, the link [`https://secure.holistics.io/dashboards/v3/16076-demo-my-beautiful-dashboard`](https://secure.holistics.io/dashboards/v3/16076-demo-my-beautiful-dashboard) will have the `source_id` of 16076.\n- `dest`: Specify the information regarding the recipients\n - `title` (string): Note that Holistics support [dynamic variables](https://docs.holistics.io/docs/delivery/email-schedules#dynamic-variables-support) in email title. For example, the title `Sales report for {{$today}}` sent on 29/09/2021 will be rendered as `Sales report for 2021-09-29 Wed`.\n\n### Schedule frequency\n\n`schedule` is used to specify the schedule for your email schedule.\n\n`repeat` (string): You will need to input a `crontab expression` here to let Holistics how frequent you want to your email schedule to run. \n\n### Dynamic filter values\n\n`dynamic-filter-presets` is where you define your filter presets here. \n\n`dynamic_filter_id` (integer): To get your `filter_id`, send a GET request to [Dashboards#Get API](#operation/Dashboards_Get) to get the dashboard info.\n\n`preset_conditions` (object): Let's go through our example to better illustrate this field.\n\nWe want to set a value for the filter by setting a preset condition. **A preset condition consists of an operator and a list of values.** Holistics supports various operators and provides several examples [here](#tag/Data-Modeling/DataModelingCondition).\n\nIn this case, we want to use operator `is` and set values to `customer_id`. By this, we mean the filter's default value equals exactly to `customer_id`.\n\nFinally, we also want to set up another dynamic filter preset to filter data to the whole of last week. Fortunately, Holistics allows a list of dynamic filter presets. For the Date Range filter, we similarly want to use operator `is` and set values to `\"last 7 days\"`.\n\nOur final `dynamic_filter_presets` object will look like this.\n\n```json\ndynamic_filter_presets = [\n {\n \"dynamic_filter_id\": MY_CUSTOMER_FILTER_ID,\n \"preset_condition\": {\n \"operator\": \"is\",\n \"values\": [\n customer_id\n ]\n }\n },\n\t{\n \"dynamic_filter_id\": MY_DATE_RANGE_FILTER_ID,\n \"preset_condition\": {\n \"operator\": \"is\",\n \"values\": [\n \"last 7 days\"\n ]\n }\n }\n]\n```\n\n## Step 3: Double-check to see if your email schedule is created\n\nThe request should now be ready. After sending it to Holistics, the server will respond with a [HTTP status response code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) to indicate whether the request was successful / failed. \n\nLastly, be sure to head over to Holistics page to see if your email schedule is created.\n\n\n\n## Example script \n\nAn example script to send requests written in Ruby is available here:\n\n```ruby\n# install the neccessary dependencies for this script to work\nrequire \"bundler/inline\"\nrequire \"net/http\"\nrequire \"json\"\n\ngemfile do\n source \"https://rubygems.org\"\n gem \"net-http\"\nend\n\n# this the Holisitics API endpoint that we need to send our POST request to\nEMAIL_SCHEDULE_ENDPOINT = URI(\"https://secure.holistics.io/api/v2/data_schedules\")\n\n# Step 1: Create a POST request to the endpoint below\nrequest = Net::HTTP::Post.new(EMAIL_SCHEDULE_ENDPOINT)\n\n# Step 2: Provide your authentication information \nrequest[\"X-Holistics-Key\"] = \"mysecretAPIkey\"\n\n# Step 2.1: This line helps the system know that we are sending a JSON request\nrequest.content_type = \"application/json\"\n\n# Step 3: Provide information for your email schedule in the request body\nrequest.body =\n {\n \"data_schedule\": {\n \"source_type\": \"Dashboard\",\n \"source_id\": 16076,\n \"schedule\": {\n \"repeat\": \"* * * * *\",\n \"paused\": false,\n },\n \"dest\": {\n \"type\": \"EmailDest\",\n \"title\": \"Sale report for {{$today}}\",\n \"recipients\": [\n \"abc@gmail.com\",\n ],\n },\n },\n }.to_json\n\n# Step 4: Send the request to Holistics!\nresponse = Net::HTTP.start(\n EMAIL_SCHEDULE_ENDPOINT.hostname,\n EMAIL_SCHEDULE_ENDPOINT.port,\n :use_ssl => EMAIL_SCHEDULE_ENDPOINT.scheme == \"https\",\n) do |https|\n https.request(request)\nend\n\n# Optional: Output the result into the terminal\nputs [response.code,response.message].join(' ')\n```\n\n# Holistics CLI\n\n>💡 **NOTE**\n>\n> The current Holistics CLI version is: 0.4.0.\n>\n> Requirements:\n> - Ruby 2.7\n\nHolistics CLI is an interface to Holistics Data Preparation module (like data transport, data transform, import). \n\n\n## Setting Up\n\n### Linux/Mac OSX\nIf you are using Linux/Mac OSX, we suggest you install Ruby with a **Ruby Version Manager** such as [rbenv](https://github.com/rbenv/rbenv) or [asdf](https://asdf-vm.com/guide/getting-started.html). \n\nPlease follow the instructions in your RVM of choice to **install Ruby 2.7.4**:\n- rbenv: https://github.com/rbenv/rbenv#installation. \n- asdf: https://asdf-vm.com/guide/getting-started.html.\n\nAfter you have Ruby installed on your computer, run:\n\n```bash\ngem install holistics -v 0.4.0\n```\n\n### Windows\nIf you are using Windows, head over to: [Official Ruby Download Page](https://rubyinstaller.org/downloads).\n\nAnd download Ruby 2.7.4 installer. Remember to select the `Devkit` option for your installer so that you \ncan run the `gem install` command in the next step from your command line. \n\nAfter you have Ruby installed on your computer, run:\n\n```bash\ngem install holistics -v 0.4.0\n```\n\n## Authentication (done once)\n\nThe next step is authentication. You first need to be granted permissions to have an API authentication token. If you are not sure how, visit: [API Authentication](#section/Authentication).\n\n\nAssuming that the above step is successful, you can access your token by going to ⚙️\nMy Account -> API Key. After that, run this in your command line to authenticate yourself.\n\n```\n$ holistics login | API V1 | \nAPI V2 | \nChanges | \n
| [User] Get all users in a tenant with full information | \nGET - List users | \n\n
| \n
| [User] Invite a new user to Holistics | \nPOST - Invite Multiple Users | \nV2 allows inviting multiple emails with additional user settings, including API usage, group IDs, and data export permissions | \n
| [User] Resend invitation to user | \nPOST - Resend invitation to user | \n\n
| \n
| [User] Soft-delete a user | \nDEL - Delete a user | \n\n |
| [User] Restore a deleted user | \nPOST - Restore a deleted user | \n\n |
| [User] Allow/ Revoke a user's API access | \nPUT - Update user | \nBy setting attribute: allow_authentication_token: boolean | \n
| [User] Revoke Authentication Token from a user | \nPUT - Update user (Upcoming) \n | \n \n |
| [User] Check whether email address is already used for a user in Holistics | \nGET - Check whether an email address is already used for a user in your Holistics workspace | \n\n |
| [User] Change user role in Holistics | \nPUT - Update user | \nBy setting attribute: “role”: enum remove_groups: passing empty group_ids | \n
| [Group] Get all groups in a tenant | \nGET - List Groups | \n\n
| \n
| [Group] Create a new group | \nPOST - Create Group | \nResponse’s structure change | \n
| [Group] Update information of an existing group | \nPUT - Update a Group | \nNow included user_ids in groups | \n
| [Group] Delete an existing group | \nDEL - Delete a Group | \n\n |
| [Group] Add a user into a group | \nPOST - Add User to Group | \n\n |
| [Group] Remove a user from a group | \nPOST - Remove User from Group | \n\n |