# Welcome *** This documentation provides everything you need to understand, integrate, and build with the Hiboo platform: * Key concepts and modules * Step-by-step guides for common use cases * Comprehensive REST API and Kafka API reference * Troubleshooting and support resources Whether you're managing fleets, building integrations, or exploring Hiboo's capabilities, you'll find clear, actionable information to help you succeed. ## What is Hiboo? > **Bridge every OEM and sensor into AI-ready data you can act on, zero blind spots.** Hiboo is a **unified platform** designed to simplify fleet management and data integration for businesses operating diverse equipment from multiple manufacturers. By harmonizing data from various OEMs, sensors, and systems, Hiboo provides a single source of truth for your fleet operations. ### **Key Capabilities** * **Data Harmonization**: Converts raw data from different OEMs and sensors into a standardized, actionable format. * **Real-Time Insights**: Delivers live updates on equipment performance, location, and utilization. * **Secure Data Sharing**: Enables controlled, one-click sharing of fleet data with partners via Hiboo Connect. ### **Why Hiboo?** * **Eliminate Complexity**: No more juggling multiple OEM systems or file formats. * **Improve Decision-Making**: Gain fleet-wide visibility to optimize operations and reduce downtime. * **Accelerate Integrations**: Build faster with clean, consistent APIs instead of managing fragmented manufacturer endpoints. * **Future-Proof Your Operations**: Stay ahead with a platform that evolves with your business and technology needs. ### **Who Uses Hiboo?** * **Fleet Managers**: Simplify operations and manage mixed fleets with ease. * **Developers & Integrators**: Build scalable applications on top of a unified data model. * **OEM Partners**: Deliver enhanced insights to customers by integrating their machines with Hiboo's platform. # Core concepts Before you touch an endpoint, it helps to know the **core concepts** that make up Hiboo and that appear throughout the API and Application. ## Fleet Administration Manage the assets you own and the metadata around them. * **Organization** – It is composed of all your machines, users, zones. It is the logical receptacle of all your data in Hiboo. One user belongs to only one organization. * **Workspace** – It belongs to an Organization, it is a group of machines, users and zones that you could map to a Business Unit, a Job type or any sub division that makes sense for your enterprise * **Equipment** – Single machine uniquely identified by an Hiboo ID. * **Custom Field** – User‑defined metadata that you attach to equipment (e.g., Cost Code, Site). * **Document** – Any file linked to equipment such as an inspection report, spec sheet or photo. ## Mixed‑Fleet Data Query harmonized telematics metrics no matter the source. * **Data Source** – the upstream system supplying raw data (e.g., Caterpillar, Komatsu, Samsara). Managed under **Catalog** in the Hiboo App. * **Integrations** - Your Organization + A Data Source + Your credentials = an Integration. Managed under **Integrations** in the Hiboo App * **Data Kind** – a normalized datapoint such as operating hours, fuel %, GPS location or fault code. ## Hiboo Connect (e.g. Data Sharing) Securely grant partners or customers scoped access to your fleet data. * **Connect Share** – a time‑bound way that exposes a chosen subset of fleet data to a third party. * **Scope** – the filters that limit what a share can see (Machine, metrics, date range). Configured when you create or edit a share. # Data Dictionary > **Note**: Not all data types are available in sandbox. Production availability depends on equipment capabilities. ## Engine & Operating Hours | Data Type | Description | Unit | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `averageDailyEngineLoadFactor` | The percentage calculated as the actual fuel consumed over the previous 24 h period divided by the fuel that would have been consumed during that period if the machine had been continually operated at the engine’s rated output. | percentage | | `cumulativeActiveRegenerationHours` | Time when the machine is placed in a non-productive state to complete the regeneration process | hours | | `cumulativeIdleHours` | Total idle hours since the initial start of the equipment. Definition of Idle hours may vary between data sources. (Also available as a daily value) | hours | | `cumulativeOperatingHours` | Total engine hours since the initial start of the equipment. (Also available as a daily value) | hours | | `engineCondition` | Running state of the engine as of the specified date and time. This data type is Boolean with false (i.e. 0) indicating not running and true (i.e. 1) indicating running. | boolean | | `engineCoolantTemperature` | Current engine coolant temperature | °C | | `engineLoadPercentage` | Current engine load vs maximum capacity | percentage | > ⚠️ **Deprecated**: `cumulativeUsageHours` duplicates `cumulativeOperatingHours` ## Fuel & Energy | Data Type | Description | Unit | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------- | | `cumulativeFuel` | Total fuel consumed since the initial start of the equipment. (Also available as a daily value) | L (liters) | | `cumulativeIdleFuel` | Total fuel consumed during idle time since the initial start of the equipment. (Also available as a daily value) | L (liters) | | `dailyCO2` | CO2 emissions for the date | kg | | `dailyEvEnergyUsed` | Daily electrical energy consumption for electric vehicles | kWh (kilowatt-hours) | | `dailyIdleFuel` | Fuel consumed during idle time for the date | L (liters) | | `defRemainingRatio` | Diesel exhaust fluid remaining in the tank, also called AUS32 or AdBlue | percentage | | `evBatteryChargeCyclesCount` | Total number of charge cycles the battery has undergone | count | | `evBatteryCurrent` | Current flowing in or out of the battery | A (amperes) | | `evBatteryHealth` | Electric vehicle battery condition | percentage | | `evBatteryLevel` | Electric vehicle battery charge remaining | percentage | | `evBatteryTemperature` | Current temperature of the battery pack | °C | | `evBatteryVoltage` | Current voltage of the battery pack | V (volts) | | `evChargingState` | Current charging status of the electric vehicle (not\_charging | charging | | `evEnergyCharged` | Total electrical energy charged into the battery | Wh (watt-hours) | | `evEnergyUsed` | Total electrical energy consumption | Wh (watt-hours) | | `fuelRemaining` | Current fuel level in tank | percentage | ## Movement & Location | Data Type | Description | Unit | | -------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `cumulativeDistance` | Total kilometers since the initial start of the equipment. (Also available as a daily value) | km | | `dailyDistance` | Distance traveled for the date | km | | `peakDailySpeed` | Maximum speed recorded on date | km/h | | `positions` | GPS location with additional context when available | {date,latitude,longitude,altitude,speed,heading} | ## Work Metrics | Data Type | Description | Unit | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `activities` | Activity is a complex kind mixing a dateStart, dateEnd, distance traveled, average speed and address of the first and last position | array<{dateStart, dateStop, distanceMeters, averageSpeedKmH, firstPositionAddress, lastPositionAddress}> | | `cumulativeLoadCount` | The total number of load cycles performed. The precise definition of load depends on the OEM. (Also available as a daily value) | count | | `cumulativePayloadTotal` | Total payload lifted, hauled, or processed. (Also available as a daily value) | tons | | `cumulativePowerTakeOffHours` | Time the power take-off was driving an implement such as a mower or sprayer. (Also available as a daily value) | hours | | `dailyLoadCount` | Number of load cycles performed for the date | count | | `dailyPayload` | Payload lifted, hauled, or processed for the date | tons | | `dailyUsages` | Comprehensive daily usage data including operating hours, idle hours | object | ## System & Diagnostics | Data Type | Description | Unit | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `batteryLevel` | The percentage of remaining battery of the asset | percentage | | `batteryVoltage` | The measured voltage of the battery of the asset | V (volts) | | `deviceBatteryLevel` | The percentage of remaining battery of the telematics device | percentage | | `deviceBatteryVoltage` | The measured voltage of the battery of the telematics device | V (volts) | | `faults` | Also called Diagnostic Trouble Codes (DTC). Fault codes are an indicator of components operating out of tolerance or failure. They are composed of a date, a short identifier, a description for more information and a level of severity (severity is a number between -1 and 3, levelLabel is the human readable from unknown to critical) | array<{date,description,identifier,severity,levelLabel}> | | `sensorBoolean` | General boolean sensor readings | boolean | | `temperature` | General temperature sensor readings | °C | # Understanding Equipment Data Mixed-fleet data is inherently complex. Integrating directly with multiple OEMs means navigating a constantly shifting landscape of APIs, data formats, and quality issues. This guide explains the challenges Hiboo solves on your behalf and provides best practices for building robust applications on the unified data we provide. ## Challenge 1: Availability & Timing Getting timely data from every machine is the first major hurdle. Availability is affected by OEM systems, machine state, and connectivity. ### How Hiboo Helps We manage a complex orchestration of API calls, respecting each source's rate limits and patterns to retrieve data as efficiently as possible. We normalize timestamps to UTC and handle out-of-order data to present a coherent timeline. **OEM API Evolution Management**: In 2023-2024, we monitored approximately **20 notable changes each year** across major OEM APIs. We absorb breaking changes, deprecated endpoints, authentication updates, and data format modifications so your integration with the Hiboo API remains stable. ### What You Should Know Even with our optimizations, the underlying source determines the data's cadence: **Varying Frequency**: Some sources provide multiple data points per minute, some provide only one data point per day. Your application should not a predefined data frequency for every machine. **Varying Freshness**: Some sources provide near real-time updates, while others send data in hourly or daily batches. Your application should not assume a constant, real-time stream for every machine. **Connectivity**: Equipment in remote locations will inevitably have delayed data. **Engine-Dependent Communication**: Many machines may only transmit data when the engine is running. This means you should expect data gaps during off-periods (nights, weekends). Data generated just before engine-off might also be delayed until the next time the machine is on. **Time Zone Variations**: OEMs may report in UTC, local time, or equipment's current location time with different formats (ISO 8601, epoch, custom formats). ## Challenge 2: Quality & Accuracy Once data arrives, its quality can vary dramatically. Raw data from the field is often noisy and contains errors. ### How Hiboo Helps Our data pipeline includes a robust validation and cleaning layer. We automatically detect and, where possible, correct common issues like: **Invalid GPS Coordinates**: Filtering out erroneous locations (e.g., `0,0`). ```json { "latitude": 0, "longitude": 0, "timestamp": "2024-01-15T10:30:00Z" } ``` **Decreasing Counters**: Identifying and flagging impossible values like decreasing odometers or hour meters. ```json { "cumulativeOperatingHours": 1250.5, // Previous reading "cumulativeOperatingHours": 1248.2 // Current reading (impossible) } ``` **Sensor Errors**: Detecting values that are physically impossible (e.g., fuel levels over 100%, extreme temperatures). We provide a **Signal Health Dashboard** in our platform to give you visibility into the quality of the underlying data streams. ### What You Should Know While we clean obvious errors, some ambiguity is inherent. A sensor might be poorly calibrated but still produce data within a "valid" range. Your system should treat the data as a highly reliable indicator, but be prepared for occasional, unfixable anomalies from the source. **Data Duplication**: Same data may be sent multiple times after connectivity loss - we handle deduplication. **Partial Updates**: Equipment systems don't always send complete data sets. We merge partial updates without losing previous values. ## Challenge 3: Consistency & Standardization Each OEM has its own proprietary data format, field names, and units, making cross-fleet analysis nearly impossible without a normalization layer. ### How Hiboo Helps This is our core value. We map dozens of disparate sources to a single, unified data model based on the **ISO 15143-3 (AEMP)** standard. **Unified Naming**: `engineHours` vs. `operatingHours` all become `cumulativeOperatingHours`. **Standardized Units**: We convert everything to metric standards (hours, liters, Celsius). **API Stability**: We absorb the ongoing API changes from OEMs. If a source changes its authentication, deprecates an endpoint, or alters a data format, we handle it. Your integration with the Hiboo API remains stable. **Beyond the Standard**: We extend the AEMP standard to support data types it doesn't cover, such as for electric vehicles, light vehicles, and power generators. ### What You Should Know Not all data kinds are available for every machine. A 10-year-old excavator will not provide the same rich data as a new electric one. When querying data, always check for the presence of a field before using it. * **Subscription Dependencies**: Higher OEM subscription tiers often include more data types. * **Model Year Differences**: Newer equipment typically provides richer data. ## Best Practices for Building on Hiboo Building with Hiboo means you're already 95% of the way there. To build truly resilient applications, embrace the nature of real-world equipment data: **Handle Nulls Gracefully**: Your code should never assume a data field will be present. Always check for `null` or `undefined` values. **Focus on Trends, Not Just Points**: A single data point might be an anomaly, but a trend over time is almost always reliable. Base critical logic on rolling averages or time-series analysis. **Use Realistic Time Windows**: When querying for data, don't assume everything arrived in the last 5 minutes. Use wider time windows (e.g., the last 24 hours) to account for batching and delays. **Trust, But Verify**: For critical workflows (like automated billing based on usage), consider adding a "reasonableness" check in your own logic as a final safeguard. **Consider Business Context**: Align expectations with operational realities - perfect data is rare, but data is often good enough for operational decisions. Understanding these realities helps build more robust, realistic systems that work effectively with real-world mixed fleet data. # Getting Started This section will guide you through the essential steps to start integrating with our mixed fleet data platform. ## What You'll Need Before diving into the API, make sure you have: * A basic understanding of REST APIs and HTTP requests * A tool for making API calls (curl, Postman, or your preferred HTTP client) * Your intended use case clearly defined, you'll find more information in the Guides & Tutorials section ## Getting Started Steps Follow these guides in order to get up and running: ### 1. Environments & Base URLs Learn about Hiboo's sandbox and production environments, including: * How to request sandbox access for testing * Production environment setup * Important differences between environments ### 2. Authenticate & Test Get your first API token and make your first successful API call: * How to obtain authentication tokens * Token refresh and expiration handling * Making your first "Hello World" API request ### 3. Using Hiboo API with Postman Set up your development tools for efficient API integration: * Download OpenAPI specifications * Import collections into Postman * Set up environment variables and authentication # Environments & Base URLs Hiboo provides two environments for development and production use. ## Sandbox Environment **Base URL**: `https://api-sandbox.hiboo.io` The sandbox environment contains generated test data to help you integrate with our API without affecting real equipment data. Use this environment for: * Initial development and testing * Integration testing * Demo applications * Learning the API structure **Sample Data Included**: * 40+ mixed fleet equipment from various manufacturers * Telemetry data updated hourly * Test sharing configurations ### Getting Sandbox Access To request sandbox credentials: 1. **Email**: 2. **Include**: Your name, company, and intended use case 3. **Response time**: Usually within 24 hours during business days ## Production Environment **Base URL**: `https://api.hiboo.io` The production environment contains your actual equipment data and should be used for: * Live applications * Customer-facing integrations * Production data access ### Getting Production Access On Hiboo App, you can manage and generate API tokens on the [Destination page](https://app.hiboo.io/destinations) ## Important Notes > ⚠️ **Credentials are not shared between environments**\ > Sandbox and production use completely separate authentication systems. > 🔒 **HTTPS Required**\ > All API calls must use HTTPS. HTTP requests will be rejected. # Authenticate & Test ## Authentication Overview To use the Hiboo REST API you must first have an existing account on Hiboo. Once you have an account, you can request for API access to our Hiboo team if you don't have access. After getting the API permission you are free to use the Hiboo REST API for your needs. Our authentication system uses `x-access-token` for validating requests. You can get the token after successful login. ### API Credentials You can create multiple API credentials on the [application](https://app.hiboo.io/destinations). Here's a breakdown of what makes a credential: * **API Name**: Must be unique. You define it and your organization name is added as a suffix `{you choice}_{organization name}` * **API Key**: Auto generated when you create a credential, you can rotate it on the application * **Workspace**: Pick the workspace your credential will have access to. * **Role**: Admin (can update data) or Viewer (read-only) **Never share your secret keys. Keep them guarded and secure.** ## Login to Get Your Token Use the login endpoint below to authenticate and receive your access token: {% openapi src="" path="/login" method="post" %} {% endopenapi %} ## Complete Authentication Flow Here's a complete example of logging in and making your first API call: {% stepper %} {% step %} #### Login Request ```bash curl -X POST "https://api.hiboo.io/login" \ -H "Content-Type: application/json" \ -d '{ "name": "api_company", "apiKey": "2ddd4027-c779-4b7c-80fe-8661c92c35ff" }' ``` {% endstep %} {% step %} #### Login Response ```json { "id": 42, "email": "api@hiboo.io", "admin": false, "firstName": "John", "lastName": "Doe", "token": "eyJhbGciOiJIfkdFVHUREIsInR5cCI6IkpXVCJ9.xxXxXXX6OXXxXxxxx3XxXXXXXx6XxXxXxxxxXX6XXX3Xxx2XxX5OXwiXXxxXxxxXXx0XxX2Xxx4xX.Ylm61gfwIgGx2bQLjtq4UkqF1MOak9y8REsVfn1GtoQ" } ``` {% endstep %} {% step %} #### Use Your Token in API Calls For all subsequent API requests, include your token in the `x-access-token` header: ```bash curl -X GET "https://api.hiboo.io/v2/fleet/equipments?limit=1" \ -H "x-access-token: eyJhbGciOiJIfkdFVHUREIsInR5cCI6IkpXVCJ9.xxXxXXX6OXXxXxxxx3XxXXXXXx6XxXxXxxxxXX6XXX3Xxx2XxX5OXwiXXxxXxxxXXx0XxX2Xxx4xX.Ylm61gfwIgGx2bQLjtq4UkqF1MOak9y8REsVfn1GtoQ" \ -H "Content-Type: application/json" ``` **Expected Response:** ```json { "data": { "total": 1, "rows": [ { "id": 1, "name": "D8000-1", "make": "Caterpillar", "model": "8000", "serialNumber": "YVR001988" } ] } } ``` {% endstep %} {% step %} **Success!** If you see a response like this, your authentication is working correctly and you're ready to explore the API. {% endstep %} {% endstepper %} ## Troubleshooting Authentication ### Common Issues **401 Unauthorized Error** * Check that your API key is correct * Verify that API access has been granted to your account * Ensure you're using the correct environment (sandbox vs production) **Token Expired** * Tokens have a limited lifetime for security * Login again to get a new token * Consider implementing automatic token refresh in your applications **Invalid Token Format** * Ensure you're using the `x-access-token` header (not `Authorization`) * Check that there are no extra spaces or characters in your token ## Token Management ### Token Expiration * Tokens have a limited lifetime for security * You'll receive a `401 Unauthorized` response when your token expires * Simply login again to get a new token ### Token Security Best Practices * **Store tokens securely** - Never hardcode them in your source code * **Use environment variables** for token storage * **Implement token refresh** in your applications * **Monitor for 401 errors** and handle re-authentication # Using Hiboo API with Postman Set up Postman to efficiently test and explore the Hiboo API with automated authentication. ## What You'll Achieve By the end of this guide, you'll have: * A fully configured Postman collection with all Hiboo API endpoints * Automatic token management (no manual copy-paste) * Pre-configured environment variables * Working authentication flow > **Alternative Tools**: This guide focuses on Postman, but you can use similar tools like [Insomnia](https://insomnia.rest/) or [Hoppscotch](https://hoppscotch.io/) with the same OpenAPI file. ## Step 1: Download Required Files 1. **Download our OpenAPI specification**: [openapiv2.yml](https://spec.hiboo.io/openapiv2.yml) 2. **Install Postman**: [Download here](https://www.postman.com/downloads/) or use the web version ## Step 2: Import the API Collection 1. **Open Postman** and click **"Import"**
Import button in Postman
2. **Upload the OpenAPI file** and select **"Postman Collection"**
Choose Postman collection option
3. **Verify import** - You should see "Hiboo API" collection in your sidebar ## Step 3: Configure Authentication Variables 1. **Prepare your API Credentials**, if you have no API credential, go to the [Hiboo API](https://app.hiboo.io/destinations), you will be able to define an `apiName` and an `apiKey` will be generated. 2. **Open collection settings** by clicking on your collection name → **Variables** tab 3. **Create these three variables**:
Collection variables configuration
| Variable Name | Initial Value | Current Value | Description | | ---------------- | --------------- | --------------- | ------------------------------------- | | `x-access-token` | *(leave empty)* | *(leave empty)* | Auto-updated after login | | `apiName` | *(leave empty)* | `your-api-name` | Your API account name generated in 1. | | `apiKey` | *(leave empty)* | `your-api-key` | Your API key generated in 1. | > **Security Note**: Only set the "Current Value" for `apiName` and `apiKey`. Be careful before setting "Initial Value" for sensitive data ([See Postman documentation for more details](https://learning.postman.com/docs/sending-requests/variables/variables/#initial-and-current-values)). 4. **Save** your variables ## Step 4: Set Up Collection-Level Authentication 1. **Go to Authorization tab** in your collection settings 2. **Select "API Key"** and configure: * **Key**: `x-access-token` * **Value**: `{{x-access-token}}` * **Add to**: `Header`
Collection authentication setup
## Step 5: Configure Automatic Login 1. **Find the `/login` endpoint** in your collection 2. **Set up the request body** with your variables: ```json { "name": "{{apiName}}", "apiKey": "{{apiKey}}" } ```
Login request body configuration
3. **Add the auto-token script** in the **Tests** tab: ```javascript // Auto-update token after successful login if (pm.response.code === 200) { const responseData = pm.response.json(); pm.collectionVariables.set("x-access-token", responseData.token); console.log("Token updated successfully"); } else { console.log("Login failed:", pm.response.text()); } ```
Login post-request script
## Step 6: Test Your Setup 1. **Execute the login request** by clicking **Send** 2. **Verify success** - You should see a response like: ```json { "id": 42, "email": "api@hiboo.io", "admin": false, "firstName": "John", "lastName": "Doe", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` 3. **Check token was saved** - Look in your collection variables; `x-access-token` should now have a value 4. **Test an authenticated endpoint**: * Open `/v2/fleet/equipments` * Ensure **Authorization** is set to **"Inherit auth from parent"** * Click **Send**
Inherit authentication setting
5. **Verify API response**:
Successful API request test
# Guides # Managing your fleet # Managing Equipment Identity Equipment identity management is essential for maintaining accurate fleet records, integrating with existing systems, and ensuring data consistency across your organization. This guide covers common scenarios for managing equipment information through the Hiboo API. ## Overview Each piece of equipment in Hiboo represents a **unique physical machine** with core identity fields: * **id**: Unique Hiboo identifier - permanently assigned to represent one physical machine * **name**: Human-readable identifier (recommended: your fleet number or asset tag) * **make**: Equipment manufacturer (e.g., "Caterpillar", "John Deere") * **model**: Equipment model (e.g., "320", "D8T") * **serialNumber**: Manufacturer's serial number * **category**: Equipment type (e.g., "Excavator", "Bulldozer") * **year**: Manufacturing year * **entreprise**: Business unit/division > **Integration Tip**: Store the Hiboo `id` in your systems as the permanent link to this physical machine. The `make + serialNumber` combination is also reliable for identification. > **Important**: Categories and entreprises must be created in the Hiboo application before they can be used via the API. ## Equipment Discovery ### Finding Equipment in Your Fleet When you need to explore what equipment is available or search for specific machines: {% openapi src="" path="/v2/fleet/equipments" method="get" %} {% endopenapi %} **Common scenarios:** * **Initial system setup**: Retrieve all equipment to understand your fleet composition * **Data audits**: Regular checks to identify missing or incorrect information * **Integration validation**: Verify equipment exists before syncing with external systems ### Getting Detailed Equipment Information When you need complete information about a specific piece of equipment: {% openapi src="" path="/v2/fleet/equipments/{id}" method="get" %} {% endopenapi %} **Use this when:** * Investigating data quality issues for specific equipment * Building detailed equipment profiles for reports * Validating information before making updates ## Data Standardization ### Correcting Equipment Names **Problem**: Equipment arrives in Hiboo with manufacturer-assigned names that don't match your internal fleet numbering system. **Solution**: Update the `name` field to use your standardized identifiers. {% openapi src="" path="/v2/fleet/equipment" method="patch" %} {% endopenapi %} **Example: Converting to fleet numbers** ```json { "assetId": 1, "name": "FLEET-001" } ``` **Example: Using location-based naming** ```json { "serialNumber": "YVR001988", "make": "Caterpillar", "name": "SITE-A-EX-01" } ``` ### Handling Inconsistent Manufacturer Data **Problem**: Equipment from different sources may have inconsistent model information, missing years, also categories are not provided and defined on Hiboo. **Common corrections:** **Standardizing model names:** ```json { "assetId": 2, "model": "320EL", "year": 2023 } ``` **Correcting equipment categories:** ```json { "assetId": 3, "category": "Backhoe Loader" } ``` > **Note**: Categories must exist in your Hiboo system. You can configure your categories in the Hiboo Application. ### Bulk Update Strategies **For large fleets**, consider these approaches: 1. **Integration-Driven**: Update equipment as part of your regular ERP/CMMS sync processes 2. **Scripted Updates**: Build scripts that iterate through equipment lists and apply standardization rules 3. **Export-Correct-Import**: Use the equipment list endpoint to export data, correct in spreadsheets, then batch update ## System Integration ### Syncing with ERP/CMMS Systems **Problem**: You need to maintain consistent equipment information between Hiboo and your existing asset management systems. **Identification Strategies:** **Option 1: Store Hiboo IDs in your system** * Store the Hiboo `id` as a field in your ERP/CMMS * Use `assetId` for all API calls (fastest, most reliable) * Recommended for new integrations **Option 2: Use manufacturer identifiers** * Match on `make + serialNumber` combination * More complex but works with existing asset databases * Good for retrofitting existing systems ### Establishing Data Mapping **Define your source of truth:** * **Names**: Use your existing fleet numbering system or use Hiboo as a source of truth * **Categories**: Standardize categories across your organization * **Model/Year**: Maintain accuracy in your asset management system **Equipment naming strategy:** * Fleet numbers: `"FLEET-001"`, `"CAT-12345"` * Asset tags: `"A-2024-078"`, `"SITE-A-EX-01"` * Avoid technical model numbers - use descriptive identifiers ### Maintaining Data Consistency **Key principles:** * **Partial updates only**: Only fields included in requests are modified - others remain unchanged * **Identification**: Use either `assetId` OR (`serialNumber` + `make`) to identify equipment # Organizing Fleet with Workspaces Workspaces enable you to organize your fleet according to your business structure, manage access permissions, and create logical groupings that align with your operational needs. This guide covers common scenarios for organizing equipment using workspaces through the Hiboo API. ## Overview Workspaces in Hiboo provide organizational structure and access control for your fleet: * **Organization Structure**: Map your business units, projects, or geographical locations * **Access Management**: Control which users can see which equipment **Key Components:** * **Users**: Team members with access to the workspace * **Machines (Assets)**: Equipment assigned to the workspace * **Zones**: Geographical or operational areas within the workspace * **Custom Fields**: Business-specific metadata relevant to the workspace > **Best Practice**: Map workspaces to your organizational structure - one workspace per business unit, project, or operational division. > **Important**: Workspaces must be created in the Hiboo application before they can be used via the API. ## Understanding Workspace Structure ### Workspace Hierarchy Workspaces follow a hierarchical structure that mirrors typical business organizations: * **Workspace Root**: The top-level workspace named after your organization that contains all your machines * **Parent Workspaces**: Business units or divisions * **Child Workspaces**: Projects, sites, or sub-divisions * **Equipment Assignment**: Machines can belong to multiple workspaces for cross-functional visibility > **Note**: Every organization has a "Workspace Root" that serves as the master container for all equipment. This root workspace is automatically named after your organization and ensures all machines remain accessible at the top level. > **Learn More**: [Understanding Workspace Hierarchy](https://help.hiboo.io/en/articles/9979011-understand-workspace-hierarchy) ### Permission Model Workspaces control data visibility and access: * **Users see only equipment** in their assigned workspaces * **Segments** can be created within workspace boundaries ## Workspace Discovery ### Viewing Available Workspaces When you need to understand your current workspace structure: {% openapi src="" path="/v2/fleet/workspaces" method="get" %} {% endopenapi %} **Common scenarios:** * **Audit workspace structure**: Review current organizational setup * **Integration planning**: Understand workspace boundaries before system integration * **User onboarding**: Identify appropriate workspaces for new team members ## Equipment Organization ### Adding Equipment to Workspaces **Problem**: You need to organize equipment by business unit, project, or location to match your operational structure. **Solution**: Link equipment to appropriate workspaces using the workspace assignment API. {% openapi src="" path="/v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces" method="post" %} {% endopenapi %} **Example: Assigning equipment to project workspace** ```json { "assetId": 1, "workspaceNames": ["Construction Site A", "Heavy Equipment"] } ``` **Example: Using manufacturer identification** ```json { "serialNumber": "YVR001988", "make": "Caterpillar", "workspaceNames": ["Project Alpha", "Earthmoving Division"] } ``` > **Recommended**: Prefer using `assetId` (Hiboo's internal ID) when possible, as it provides faster, more reliable equipment identification and avoids potential issues with duplicate serial numbers or manufacturer name variations. ### Removing Equipment from Workspaces **Problem**: Equipment moves between projects or organizational changes require workspace restructuring. **Solution**: Remove equipment from specific workspaces while maintaining other workspace assignments. {% openapi src="" path="/v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces" method="delete" %} {% endopenapi %} **Example: Removing equipment from completed project** ```json { "assetId": 1, "workspaceNames": ["Project Beta"] } ``` > **Best Practice**: When updating workspace assignments, use differential updates rather than deleting all workspace assignments and recreating them. This approach: > > * Preserves historical data and audit trails > * Reduces API calls and processing overhead > * Minimizes risk of data loss during updates > * Maintains workspace permissions and relationships during transitions > **Note**: Removing an asset from a workspace will also remove the history of the machine in this workspace as it has never been in the workspace. ## Common Organization Patterns ### Business Unit Structure **Scenario**: Large organization with multiple divisions operating independently. **Pattern**: Create top-level workspaces for each division: * **Construction Division** → All construction equipment * **Mining Division** → All mining equipment * **Forestry Division** → All forestry equipment **Implementation:** ```json { "assetId": 123, "workspaceNames": ["Construction Division"] } ``` ### Geographical Organization **Scenario**: Multi-location operations with regional management. **Pattern**: Organize by location hierarchy: * **North America** → Regional workspace * **Canada Operations** → Country-level workspace * **Alberta Projects** → Province/state workspace **Implementation:** ```json { "assetId": 789, "workspaceNames": ["North America", "Canada Operations", "Alberta Projects"] } ``` ### Hybrid Organization **Scenario**: Complex operations requiring multiple organizational views. **Pattern**: Equipment belongs to multiple workspace categories: * **Business function** (Construction, Mining) * **Geographic location** (Site A, Site B) * **Equipment type** (Heavy Equipment, Light Vehicles) **Implementation:** ```json { "assetId": 101, "workspaceNames": ["Construction Division", "Site A", "Heavy Equipment"] } ``` ## Integration Strategies ### ERP/CMMS System Alignment **Problem**: Your existing systems have organizational structures that need to map to Hiboo workspaces. **Strategies:** **Project Code Integration:** * Use project codes to determine workspace assignments * Automate equipment moves when project assignments change * Track equipment utilization by project **Location Hierarchy Sync:** * Mirror your CMMS location structure in workspace hierarchy * Sync equipment location changes to workspace assignments * Maintain geographical reporting consistency ## Best Practices ### Workspace Design Principles **Keep it Simple:** * Start with your primary organizational structure * Avoid over-complicating with too many workspace levels * Focus on how your teams actually work **Plan for Change:** * Design workspace structure that can evolve with your business * Use descriptive names that won't become outdated * Consider equipment mobility between workspaces **Match User Needs:** * Align workspaces with how users need to view and manage equipment * Enable cross-functional visibility where needed * Balance access control with operational efficiency ### Workspace Management **Naming Conventions:** * Use consistent, descriptive workspace names * Include relevant identifiers (project codes, location codes) * Avoid abbreviations that might be unclear **Assignment Strategy:** * **Multiple assignments**: Equipment can belong to multiple workspaces for different organizational views * **Minimal assignments**: Don't over-assign - keep it relevant to actual business needs * **Regular review**: Audit workspace assignments as projects and organizations change # Adding Custom Fields to Equipment Custom fields enable you to extend equipment data beyond standard specifications, capturing business-specific information that's essential for your operations, reporting, and decision-making. This guide covers common scenarios for working with custom fields through the Hiboo API. ## Overview Custom fields allow you to add extra data to your equipment and tailor Hiboo's usage to the needs of your organization. They provide flexibility to capture business-specific metadata that standard equipment fields don't cover. **Key Components:** * **Name**: Field identifier for API access * **Description**: Human-readable explanation of the field's purpose * **Workspaces**: Where the field will be available (scope control) * **Format**: Data type (Text, Number, Select, URL) * **Options**: Available choices (for Select fields only) > **Note**: Currently, the Select type is the only one allowing filtering on Hiboo Application. > **Important**: Custom fields must be created in the Hiboo application before they can be used via the API. See [Custom Fields Help Center](https://help.hiboo.io/en/articles/10146204-custom-fields) for setup instructions. ## Common Use Cases ### Contract Management **Scenario**: Track rental vs. owned equipment for financial reporting and contract management. **Solution**: Create a "Contract Status" select field to differentiate equipment ownership. **Typical values:** * "Owned" * "Rented - Short Term" * "Rented - Long Term" * "Leased" ### Asset Lifecycle Tracking **Scenario**: Capture purchase dates and financial information for depreciation and asset management. **Solution**: Add date and financial fields to track asset lifecycle. **Common fields:** * **Purchase Date**: When the equipment was acquired * **Purchase Price**: Original cost for depreciation calculations * **Warranty Expiry**: Service coverage end date ### Maintenance Planning **Scenario**: Communicate equipment condition and maintenance needs across teams. **Solution**: Create condition and status fields for maintenance planning. **Example categories:** * **Condition**: "Excellent", "Good", "Fair", "Poor", "Out of Service" * **Maintenance Priority**: "Low", "Medium", "High", "Critical" * **Last Service Date**: Track maintenance history ### Operational Status Tracking **Scenario**: Monitor operational status for specialized equipment like dumpsters or delivery vehicles. **Solution**: Create status fields that reflect current operational state. **Example for dumpsters:** * **Container Status**: "Empty", "Partial", "Full", "In Transit" * **Material Type**: "Construction Debris", "Recycling", "General Waste" * **Service Route**: Geographic or operational routing information ## Reading Custom Field Data ### Retrieving Equipment with Custom Fields When you need to access equipment data including custom field values: {% openapi src="" path="/v2/fleet/equipments" method="get" %} {% endopenapi %} **Use this when:** * Building equipment dashboards that include business-specific data * Generating reports that combine standard and custom field information * Syncing equipment data with external systems that use custom fields ### Getting Custom Field Values for Specific Equipment When you need detailed custom field information for a specific piece of equipment: {% openapi src="" path="/v2/fleet/equipments/{id}" method="get" %} {% endopenapi %} **Use this when:** * Building detailed equipment profiles * Validating custom field data before updates * Troubleshooting data synchronization issues ## Updating Custom Field Values ### Setting Custom Field Values **Problem**: You need to update business-specific information like contract status, condition, or operational data. **Solution**: Use the custom fields API to add or update custom field values. {% openapi src="" path="/v2/fleet/equipment/assetCustomFields" method="post" %} {% endopenapi %} **Example: Updating contract and condition information** ```json { "assetId": 123, "customFields": [ { "label": "contractStatus", "value": "Rented - Long Term" }, { "label": "condition", "value": "Excellent" }, { "label": "lastServiceDate", "value": "2024-07-15" } ] } ``` **Example: Using manufacturer identification** ```json { "assetId": 234, "customFields": [ { "label": "containerStatus", "value": "Full" }, { "label": "materialType", "value": "Construction Debris" }, { "label": "serviceRoute", "value": "Downtown Zone A" } ] } ``` **Example: Financial tracking update** ```json { "assetId": 456, "customFields": [ { "label": "purchaseDate", "value": "2023-12-01" }, { "label": "purchasePrice", "value": "125000" }, { "label": "warrantyExpiry", "value": "2026-12-01" } ] } ``` > **Recommended**: Prefer using `assetId` (Hiboo's internal ID) when possible for faster, more reliable equipment identification. ## Best Practices ### Custom Field Design **Field Naming:** * Use clear, descriptive names that match your business terminology * Be consistent across your organization * Avoid technical abbreviations that might be unclear **Data Types:** * **Text**: Free-form information (notes, descriptions) * **Number**: Costs, quantities, measurements * **Select**: Standardized categories (status, condition, type) * **URL**: Links to documents, photos, or external systems **Value Standardization:** * Use consistent formats for dates (ISO 8601: YYYY-MM-DD) * Standardize status values across your organization * Create clear option lists for select fields ### Data Management **Update Strategy:** * **Partial updates**: Only update fields that have changed * **Validation**: Ensure values match expected formats and options * **Batch operations**: For large fleets, consider scripted updates **Data Quality:** * Regular audits to ensure data consistency * Clear processes for updating custom field values * Training for users who manage custom field data # Attaching Documents to Equipment Document management enables you to attach important files directly to equipment profiles, creating a centralized repository where your team can access maintenance logs, technical documentation, compliance certificates, and other critical information. This guide covers common scenarios for managing equipment documents through the Hiboo API. ## Overview Documents in Hiboo provide a secure way to store and share files associated with specific equipment. By adding documents to your equipment's profile, Hiboo becomes your fleet's source of truth, enabling each team member to find the right document in a dedicated place. **Common Document Examples:** * **Safety inspection reports**: Periodic safety inspections and compliance documentation * **Maintenance logs**: Service history and repair records * **Technical documentation**: Manuals, specifications, and operating instructions * **Compliance certificates**: Safety inspections, regulatory approvals * **Inspection reports**: Regular condition assessments **Key Features:** * **File size limit**: Maximum 10MB per document * **Supported formats**: PDF, JPG, PNG, GIF, TIFF, CSV, XLS, XLSX, DOC, DOCX * **Sharing control**: Documents can be shared automatically with customers when equipment is shared through Hiboo Connect * **Public access**: Documents can be made publicly accessible via QR codes in Hiboo Field > **Learn More**: See [Documents Help Center](https://help.hiboo.io/en/articles/10206444-documents) for additional setup and usage information. ## Document Discovery ### Viewing Equipment Documents When you need to see what documents are available for specific equipment: {% openapi src="" path="/v2/fleet/equipments/{id}/documents" method="get" %} {% endopenapi %} **Common scenarios:** * **Document audit**: Review what documentation exists for equipment * **Compliance verification**: Ensure required documents are attached * **Team access**: Help users find relevant documentation ## Document Upload ### Adding Documents to Equipment **Problem**: You need to attach important files like maintenance records, compliance certificates, or technical documentation to equipment profiles. **Solution**: Upload documents directly to equipment using the document upload API. {% openapi src="" path="/v2/fleet/equipments/{id}/documents" method="post" %} {% endopenapi %} **Example: Uploading a maintenance report** ```json { "name": "Annual Maintenance Report 2024", "file": "[binary file data]", "shareable": false, "isPublic": false, "expirationDate": "2025-12-31" } ``` **Example: Uploading public technical documentation** ```json { "name": "Operator Manual v3.2", "file": "[binary file data]", "shareable": false, "isPublic": true, "expirationDate": null } ``` **Example: Uploading shareable safety certificate** ```json { "name": "Safety Inspection Certificate 2024", "file": "[binary file data]", "shareable": true, "isPublic": false, "expirationDate": "2025-12-31" } ``` ## Document Management ### Updating Document Information **Problem**: You need to modify document metadata like names, sharing permissions, or expiration dates without re-uploading the file. **Solution**: Update document properties using the document patch API. {% openapi src="" path="/v2/fleet/equipments/{id}/documents/{documentId}" method="patch" %} {% endopenapi %} **Example: Updating document name and expiration** ```json { "name": "Updated Safety Inspection Report 2024", "expirationDate": "2026-01-31" } ``` **Example: Extending document validity** ```json { "expirationDate": "2025-12-31" } ``` ### Removing Documents **Problem**: Documents become outdated, irrelevant, or need to be replaced with newer versions. **Solution**: Delete documents that are no longer needed. {% openapi src="" path="/v2/fleet/equipments/{id}/documents/{documentId}" method="delete" %} {% endopenapi %} **Use this when:** * Documents have expired and are no longer valid * Replacing old versions with updated files * Removing incorrectly uploaded documents * Cleaning up document libraries for better organization ## Document Access ### Downloading Documents **Problem**: You need to retrieve document files for offline use, sharing, or integration with other systems. **Solution**: Download documents using the document download API. {% openapi src="" path="/v2/fleet/equipments/{id}/documents/{documentId}/download" method="get" %} {% endopenapi %} **Common scenarios:** * **Offline access**: Download for field use without internet * **System integration**: Import documents into other management systems * **Backup procedures**: Create local copies for disaster recovery * **Audit trails**: Retrieve historical documentation for compliance ## Common Use Cases ### Compliance Documentation **Scenario**: Track regulatory compliance documents that expire and require regular renewal, while sharing relevant certificates with customers when needed. **Strategy**: * Use descriptive naming with dates: "Safety Inspection Report 2024", "Safety Inspection Q3-2024" * Set expiration dates to match regulatory requirements * Make safety certificates and compliance documents shareable when required by customers for their own compliance * Use public access for field inspections via QR codes * Keep internal regulatory paperwork private (shareable: false) **Example workflow:** 1. Upload compliance certificate with expiration date 2. Set as shareable only if customers need it for their own regulatory compliance 3. Monitor expiration dates for renewal planning 4. Replace expired documents with updated versions **Customer-relevant compliance documents:** * **"Safety Inspection Certificate 2024"** → Shareable (customers may need for site access) * **"Equipment Specification Sheet"** → Shareable (helps customers plan usage) * **"Environmental Compliance Certificate"** → Shareable (required for some job sites) * **"Operator Training Certification"** → Shareable (proves operator qualification) **Document sharing guidelines:** * **Shareable**: Safety certificates, equipment specs, operator qualifications, environmental compliance - documents customers need for their own compliance or operations * **Private**: Internal audit reports, regulatory correspondence, internal compliance tracking, maintenance costs, business-sensitive information ### Maintenance Documentation **Scenario**: Maintain comprehensive service records and technical documentation for each piece of equipment. **Strategy:** * Organize by document type: "Maintenance Log", "Service Manual", "Parts Catalog" * Keep maintenance logs and repair records private (internal operational data) * Make technical manuals and safety guides publicly accessible for operators * Track service history through chronological uploads **Example document organization:** * **"Service Manual CAT 320EL"** → Public, no expiration (operators need access) * **"Maintenance Log 2024"** → Private, expires end of year (internal tracking) * **"Hydraulic System Repair 2024-07"** → Private, permanent record (internal service history) * **"Safety Operating Procedures"** → Public, no expiration (operator safety) **Document sharing guidelines:** * **Public**: Operator manuals, safety procedures, troubleshooting guides * **Private**: Maintenance logs, repair records, service history, cost information ### Field Operations Support **Scenario**: Provide operators and field teams with immediate access to equipment documentation. **Strategy:** * Make operator manuals and safety guides publicly accessible * Use QR codes on equipment for instant document access * Include troubleshooting guides and emergency procedures * Ensure critical documents have no expiration dates **Benefits:** * Operators can access manuals via smartphone scanning * Reduced need for physical documentation on equipment * Always up-to-date information in the field * Improved safety through accessible safety procedures **Document guidelines:** * **Public**: Operator manuals, safety procedures, emergency contacts, basic troubleshooting * **Private**: Detailed repair procedures, maintenance schedules, cost information ## Integration Strategies ### Document Lifecycle Management **Problem**: You need to automate document management as part of your maintenance and compliance workflows. **Key approaches:** * **Automated upload**: Integrate with maintenance/compliance systems to upload reports and certificates automatically * **Expiration monitoring**: Build alerts for documents approaching expiration and flag equipment with expired compliance documents * **Version control**: Use naming conventions with version numbers and maintain audit trails of document changes ### System Integration **Problem**: Your existing document management or maintenance systems need to sync with Hiboo document storage. **Key strategies:** * **Document synchronization**: Export from existing systems and upload to Hiboo, or use Hiboo as the master repository * **Workflow integration**: Trigger uploads when work orders complete and set appropriate sharing permissions automatically * **Access control alignment**: Set sharing permissions based on document type and customer needs while maintaining security policies ## Best Practices ### Document Organization **Naming Conventions:** * Use clear, descriptive names that include dates when relevant * Include equipment identifiers for easy searching * Use consistent terminology across your organization * Avoid special characters that might cause issues **File Management:** * Optimize file sizes before upload (compress images, reduce PDF sizes) * Use appropriate file formats for content type * Regularly review and clean up outdated documents * Maintain consistent quality standards for uploads **Access Control:** * Set sharing permissions thoughtfully - only share documents that provide value to customers * Use public access for operational documents that operators need in the field * Consider security implications of document sharing with external parties * Regularly audit document access permissions ### Compliance and Security **Document Retention:** * Set appropriate expiration dates for regulatory requirements * Implement backup procedures for critical compliance documents * Plan for document archival and retention policies **Quality Control:** * Validate document content before upload * Ensure documents are complete and readable * Maintain version control for updated documents * Regular quality audits of document libraries **Sharing Guidelines:** * **Shareable**: Safety certificates, equipment specifications, compliance documents customers need * **Private**: Maintenance logs, repair costs, internal assessments, business-sensitive information * **Public**: Operator manuals, safety procedures, troubleshooting guides # Managing Equipment Lifecycle Equipment lifecycle management enables you to track your equipment through different operational states, from active operation to retirement. This ensures accurate fleet visibility, proper data collection management, and organized equipment transitions. This guide covers common scenarios for managing equipment status changes through the Hiboo API. ## Overview Equipment in Hiboo can exist in three distinct states, each serving different business purposes and affecting data collection: **Equipment Status Types:** * **ACTIVE**: Part of your operational fleet, actively receiving and processing data * **ARCHIVED**: Equipment no longer in active service but with preserved historical data access * **DELETED**: Equipment completely removed from your fleet (typically for data correction purposes) **Key Business Rules:** * Equipment must be **unshared** before it can be archived * Equipment must be **archived** before it can be deleted * Data collection **stops immediately** when equipment is archived * Historical data **remains accessible** for archived equipment * Data collected during archiving period is **permanently unavailable** when restored * Equipment deletion is **irreversible** > **Learn More**: See [Equipment Archiving Help Center](https://help.hiboo.io/en/articles/10081926-archiving-and-deleting) for additional operational information. ## Status Discovery ### Checking Equipment Status When you need to understand the current operational state of equipment: {% openapi src="" path="/v2/fleet/equipments/{id}/status" method="get" %} {% endopenapi %} **Common scenarios:** * **Fleet auditing**: Review operational status across your entire fleet * **Compliance tracking**: Ensure proper documentation of equipment transitions * **System integration**: Validate equipment state before performing operations * **Troubleshooting**: Understand why equipment might not be receiving data ## Equipment Archiving ### Moving Equipment Out of Active Service **Problem**: You need to remove equipment from active operations while preserving historical data access for compliance, reporting, or future reference. **Solution**: Archive equipment to stop data collection while maintaining access to historical information. {% openapi src="" path="/v2/fleet/equipments/{id}/status/archived" method="post" %} {% endopenapi %} **Example: End-of-life equipment retirement** ```json { "comment": "Equipment reached end-of-life and replaced with newer model CAT-2024-001" } ``` **Example: Equipment sale transition** ```json { "comment": "Equipment sold to ABC Construction - reference sale order SO-2024-156" } ``` **Example: Maintenance removal** ```json { "comment": "Removed from active fleet for major overhaul - estimated return Q2 2025" } ``` **Use this when:** * **Equipment sales**: Transferring ownership to another organization * **End-of-life retirement**: Equipment no longer economically viable to operate * **Long-term maintenance**: Extended repairs or refurbishment periods ## Equipment Restoration ### Returning Equipment to Active Service **Problem**: Previously archived equipment needs to return to active operations, resuming data collection and fleet visibility. **Solution**: Restore archived equipment to active status to resume normal operations. {% openapi src="" path="/v2/fleet/equipments/{id}/status/active" method="post" %} {% endopenapi %} **Use this when:** * **Post-maintenance return**: Equipment repairs completed and ready for service * **Lease return**: Equipment returned from lease and back in your direct fleet **Important considerations:** * Data collection resumes immediately upon restoration * Any data that would have been collected during archiving period is **permanently unavailable** * Equipment returns to your active inventory and operational dashboards * Historical data from before archiving remains fully accessible ## Equipment Deletion ### Permanently Removing Equipment from Fleet **Problem**: Equipment was incorrectly added to your fleet or needs complete removal for data accuracy purposes. **Solution**: Delete equipment to completely remove it from your system (requires prior archiving). {% openapi src="" path="/v2/fleet/equipments/{id}" method="delete" %} {% endopenapi %} **Use this when:** * **API integration errors**: Equipment incorrectly imported from data sources * **Duplicate entries**: Multiple records created for the same physical equipment * **Data correction**: Wrong equipment information that cannot be updated * **System cleanup**: Removing test or invalid equipment records **Critical considerations:** * **Equipment must be archived first** before deletion * **Action is irreversible** - equipment disappears entirely from the system * **All associated data becomes permanently inaccessible** * **Use sparingly** - archiving is usually the preferred approach ## Common Use Cases ### Equipment Lifecycle Transitions **Scenario**: Manage planned equipment transitions including sales, replacements, and upgrades while maintaining operational continuity. **Strategy:** * Plan archiving timing to minimize operational disruption * Document replacement equipment details in archiving comments * Coordinate with maintenance teams for pre-archiving inspections * Ensure proper handover documentation for equipment sales **Example transition management:** 1. **Pre-archiving**: Complete final maintenance, document condition 2. **Archive with context**: "Replaced by CAT-2024-001 - final hours: 8,450" 3. **Sales coordination**: Share historical data with buyers if contractually required 4. **Activate replacement**: Ensure new equipment integration is complete ### Maintenance Management **Scenario**: Equipment requires extended maintenance periods that exceed normal operational downtime expectations. **Strategy:** * Archive equipment during extended maintenance to stop unnecessary alerts * Use detailed comments to track maintenance scope and timeline * Coordinate with maintenance teams on expected completion dates * Plan for systematic reactivation testing **Maintenance archiving examples:** * **"Major overhaul - engine rebuild, hydraulic system replacement - ETA 16 weeks"** * **"Accident damage repair - awaiting insurance approval and parts availability"** * **"Transmission replacement - specialized repair facility - return date TBD"** ## Best Practices ### Status Change Documentation **Comment Guidelines:** * Include specific business reasons for status changes * Reference related equipment, projects, or business events * Provide timeline information when relevant * Use consistent terminology across your organization **Documentation Examples:** * **Good**: "Replaced by newer model DEF-2024-002 due to high maintenance costs - final service hours: 12,450" * **Poor**: "No longer needed" ### Timing Considerations **Archiving Timing:** * Archive equipment immediately when removed from service to stop data alerts * Coordinate archiving with maintenance schedules to avoid confusion * Plan archiving around reporting periods to maintain data consistency * Consider operational impact when multiple pieces of equipment are archived simultaneously # Connecting a Data Source via OAuth Some data sources — John Deere, CASE, Wacker Neuson, and others — don't accept a static API key. Instead, the equipment owner must log in on the manufacturer's own portal and explicitly grant Hiboo access. This is the standard OAuth2 **authorization code** flow, and this guide walks through how to drive it from your own application. ## Why OAuth The whole point of the OAuth2 flow is that your application — and Hiboo — never see the end user's personal data source credentials (their email and password on the manufacturer's portal). Instead: 1. The user's browser is sent directly to the data source's own login/consent page. 2. On success, the data source hands Hiboo a short-lived authorization **code**. 3. Hiboo exchanges that code for an **access token** and a **refresh token**, which it then uses to pull equipment data on an ongoing basis. Some data sources also require supplementary app credentials to identify the calling application — typically a `clientId` / `clientSecret` pair issued by the manufacturer. Where required, you pass these along as `integrationCredentials` when you start the flow — see [Supported data sources](#supported-data-sources) below. ## The three actors | Actor | Role | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | **Your application** | A partner frontend. Starts the flow and receives the final redirect. | | **Hiboo API** | Creates and tracks the OAuth session, exchanges the code for tokens, and creates or updates the [Integration](/guides/core-concepts). | | **Data source's OAuth portal** | Where the end user authenticates and consents (e.g. `signin.johndeere.com`). | > **Base URL**: the OAuth endpoints below are served from `https://ingest.hiboo.io`. ## Flow overview 1. Your backend calls `POST https://ingest.hiboo.io/catalog/integrations/oauth` with the data source and the credentials you already have. Hiboo creates a pending OAuth session and returns an `oauthUrl` and a `sessionId`. 2. You open `oauthUrl` in the user's browser. The user logs in directly with the data source. 3. The data source redirects the browser to Hiboo's **fixed** callback URL (`https://ingest.hiboo.io/oauth/callback`) with an authorization `code` and `state` (the `sessionId`). 4. Hiboo exchanges the code for tokens, creates the Integration, and redirects the browser to the `redirectUri` **you** provided in step 1. 5. Optionally, you can poll `GET https://ingest.hiboo.io/catalog/integrations/oauth/{sessionId}` to fetch the outcome server-side instead of relying solely on the redirect. > **Don't confuse the two URLs:** > > * **Callback URL** — constant, owned by Hiboo (`https://ingest.hiboo.io/oauth/callback`). This is where the data source sends the user back to. > * **Redirect URL** — yours, passed as `redirectUri`. This is where Hiboo sends the user back to once the exchange is done. ## Step 1: Start the OAuth session ``` POST https://ingest.hiboo.io/catalog/integrations/oauth x-access-token: Content-Type: application/json { "dataSourceCode": "wacker_neuson_aemp_2", "integrationName": "Wacker Neuson - Main fleet", "integrationCredentials": { "clientId": "your-wacker-neuson-client-id", "clientSecret": "your-wacker-neuson-client-secret" }, "redirectUri": "https://app.hiboo.io/integrations/oauth/callback" } ``` **Body parameters:** | Field | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | `dataSourceCode` | One of the [supported OAuth data sources](#supported-data-sources). | | `integrationName` | A name for the resulting Integration. | | `integrationCredentials` | Supplementary credentials the data source requires (`{}` if none — see [Supported data sources](#supported-data-sources)). | | `redirectUri` | Where Hiboo sends the user's browser once the flow completes, success or failure. | Requires an authenticated **organization admin** (`x-access-token` header, admin role). **Response — `200 OK`:** ```json { "oauthUrl": "https://signin.johndeere.com/oauth2/.../v1/authorize?client_id=...&state=...", "sessionId": "b3f1c2a4-....." } ``` | Status | Cause | | ------ | ---------------------------------------------------------------------------------- | | `401` | Missing or invalid token. | | `403` | Authenticated user is not an organization admin. | | `409` | An Integration already exists for this organization, data source, and credentials. | | `422` | Unsupported `dataSourceCode`, or invalid body. | ## Step 2: Send the user to the data source Redirect the browser (or open a webview) to the `oauthUrl` returned in step 1. The user authenticates and consents entirely on the data source's own domain — your application is not involved in that exchange. ## Step 3: The data source calls Hiboo back The data source redirects the browser to Hiboo's callback endpoint with the authorization code and the `state` you never touch directly — it's the `sessionId` from step 1, round-tripped for you: ``` GET https://ingest.hiboo.io/oauth/callback?code=&state= ``` Hiboo looks up the pending session by `sessionId`, exchanges the code for an access token and a refresh token with the data source, and creates the Integration (storing the tokens as its credential). ## Step 4: Hiboo redirects back to your application Once the exchange completes (or fails), Hiboo redirects the browser to the `redirectUri` you supplied in step 1, with query parameters appended: **On success:** ``` https://app.hiboo.io/integrations/oauth/callback?status=completed&integrationId=42&sessionId=b3f1c2a4-... ``` **On failure:** ``` https://app.hiboo.io/integrations/oauth/callback?status=error&sessionId=b3f1c2a4-... ``` > The error redirect does not include the failure reason — read it via step 5 if you need to display it to the user. ## Step 5 (optional): Poll for the result If you'd rather confirm the outcome from your backend than parse redirect query parameters — useful for mobile deep links, or as a safety net if the redirect gets interrupted — poll: ``` GET https://ingest.hiboo.io/catalog/integrations/oauth/{sessionId} x-access-token: ``` **Response — `200 OK`:** ```json { "status": "completed", "integrationId": 42 } ``` or ```json { "status": "error", "reason": "Failed to authenticate with John Deere: invalid_grant" } ``` | Status | Cause | | ------ | ------------------------------------------------------------------------------------------------------------------------------- | | `404` | No result for this `sessionId` — not found, expired, or not yet completed. Results are kept for **5 minutes** after completion. | | `403` | The session belongs to another organization. | ## Re-authenticating an existing Integration Access and refresh tokens can be revoked or expire. To reconnect an existing Integration without recreating it, start the same flow against the Integration instead of the data source: ``` POST https://ingest.hiboo.io/catalog/integrations/{integrationId}/oauth x-access-token: Content-Type: application/json { "redirectUri": "https://app.hiboo.io/integrations/oauth/callback" } ``` This reuses the Integration's stored credentials and data source, so you don't repeat `dataSourceCode` or `integrationCredentials`. Steps 2–5 are identical — on success, the **existing** `integrationId` is reactivated with fresh tokens rather than a new Integration being created. | Status | Cause | | ------ | ----------------------------------------------------------- | | `404` | No Integration with this `integrationId`. | | `403` | The Integration belongs to another organization. | | `422` | This data source no longer supports OAuth, or invalid body. | ## Supported data sources | `dataSourceCode` | Data source | Supplementary `integrationCredentials` | | ---------------------- | ---------------------------- | ----------------------------------------------------------- | | `johndeere_aemp_2_0` | John Deere (AEMP 2.0) | None — pass `{}` | | `johndeere_operations` | John Deere Operations Center | None — pass `{}` | | `case_aemp_2` | CASE (AEMP 2.0) | None — pass `{}` | | `wacker_neuson_aemp_2` | Wacker Neuson (AEMP 2.0) | `clientId`, `clientSecret` (issued to you by Wacker Neuson) | ## Pending session lifetime An OAuth session created in step 1 is only held for **15 minutes**. If the user doesn't complete the data source login within that window, the `sessionId` expires and the callback in step 3 will fail — start over from step 1. # Working with Mixed Fleet Data # Setting up efficient polling strategies Understanding when and how often to poll Hiboo's API ensures you get the data you need while maintaining system efficiency. This guide covers the essential polling patterns for different business scenarios. ## Overview Hiboo processes equipment data in near real-time as it's received from various data sources, but transmission patterns vary significantly across equipment brands and operational scenarios. **Key Data Characteristics:** * **Near real-time processing**: Data is computed immediately when received by Hiboo * **Variable transmission timing**: Equipment sends data based on events or fixed schedules, depending on the source * **Delayed data scenarios**: Some data only transmits when specific conditions are met **Common Delay Examples:** * **Engine-off reporting**: Some brands only report "Engine off" events when the engine restarts * **Weekend gaps**: Reduced connectivity and activity during weekends * **Connectivity issues**: Remote locations may have intermittent data transmission **Recommended Baseline Strategy:** * **Frequent monitoring**: Multiple polls per day/hour for operational data * **Weekly catch-up**: 10-day data windows to capture delayed transmissions ## Real-Time Fleet Monitoring ### Current Fleet Activity **Problem**: You need current operational information for your entire fleet to support operational decisions and monitoring dashboards. **Solution**: Use snapshot endpoints for immediate equipment status across your fleet. {% openapi src="" path="/v2/fleet/equipments/snapshot" method="get" %} {% endopenapi %} **Recommended polling frequency:** * **Operational hours**: Every 15-30 minutes (6 AM - 6 PM) * **Off-hours**: Every 60 minutes * **Weekends**: Every 2-4 hours (unless 24/7 operations) ### Individual Equipment Monitoring **Problem**: You need detailed current activity for specific high-value or critical equipment pieces. **Solution**: Poll individual equipment snapshots for focused monitoring. {% openapi src="" path="/v2/fleet/equipments/{id}/snapshot" method="get" %} {% endopenapi %} **Use this approach when:** * **Critical equipment**: High-value assets requiring constant monitoring * **Active projects**: Equipment currently deployed on important jobs * **Performance tracking**: Detailed monitoring of specific equipment performance **Recommended polling patterns:** * **Critical equipment**: Every 5-15 minutes during active use * **Standard monitoring**: Every 30 minutes during operational hours ## Historical Data Collection ### Comprehensive Equipment Data History **Problem**: You need comprehensive historical data for analysis, reporting, and compliance requirements. **Solution**: Use time series endpoints with strategic time windows to capture complete data sets. {% openapi src="" path="/v2/fleet/equipments/{id}/{dataKind}" method="get" %} {% endopenapi %} **Time window strategies:** **Recent data collection:** ``` Window: Last 24-48 hours Frequency: Every 6-8 hours Purpose: Capture recent operational data ``` **Weekly catch-up collection:** ``` Window: Last 10 days Frequency: Weekly (e.g., Sunday nights) Purpose: Capture delayed data and ensure completeness ``` ### Simplified Equipment History **Problem**: You need one endpoint for historical data including positions, fault codes, daily usage patterns, and operational metrics for comprehensive analysis. **Solution**: Use equipment history endpoints for consolidated historical data across multiple data types. {% openapi src="" path="/v2/fleet/equipments/{id}/history" method="get" %} {% endopenapi %} **What this endpoint provides:** * **Position history**: Equipment locations over time * **Fault codes**: Diagnostic events and equipment issues * **Fuel data**: Remaining fuel levels and consumption patterns * **Engine conditions**: Running/idle status history * **Daily usage summaries**: Operating hours, idle time, working hours, distances * **Cumulative metrics**: Total hours, fuel consumption, distance, load counts, payload * **Performance data**: Speed patterns, load factors, emissions (CO2), DEF levels **Use this endpoint when:** * **Comprehensive reporting**: You need multiple data types in a single request * **Dashboard overviews**: Consolidated view of equipment performance * **Historical analysis**: Studying patterns across different operational metrics **Strategic polling approach:** * **Daily collection**: Previous day's data every morning (captures overnight transmissions) * **Weekly collection**: Previous week's data every Monday (catches weekend delays) **Note**: For specific data types with higher frequency or detailed time-series analysis, use the `/{dataKind}` endpoint described above. ## Best Practices ### Polling Frequency Guidelines **High-frequency (every 5-15 minutes):** * Critical equipment monitoring * Real-time dashboard updates * Active project tracking **Medium-frequency (every 30 minutes - 2 hours):** * Standard fleet monitoring * Performance tracking * Operational oversight **Low-frequency (daily/weekly):** * Historical data collection * Compliance reporting * Long-term analysis ### Time Window Strategy **Recent data (last 24-48 hours):** * Operational monitoring * Real-time decision making * Current status tracking **Catch-up data (last 7-10 days):** * Complete data collection * Weekend/holiday coverage * Data quality assurance ### Implementation Tips **Error handling:** * Implement retry logic for temporary failures * Track last successful poll timestamps * Use overlapping time windows to ensure completeness **Performance optimization:** * Use appropriate pagination for large fleets * Cache recent data to reduce redundant requests * Schedule bulk operations during low-activity periods **Monitoring:** * Track polling success rates and response times * Alert on extended periods without successful data collection * Regular review of polling strategies against business needs # Synchronizing with a Data Lake Data lakes are essential for organizations managing large fleets across multiple brands and operational environments. This guide covers strategies for efficiently synchronizing Hiboo equipment data with your data lake infrastructure while maintaining data quality and operational efficiency. ## Overview Data lake synchronization with Hiboo leverages our unified API to streamline mixed fleet data management. While traditional fleet management faces challenges with different equipment brands and data formats, Hiboo normalizes this complexity, allowing you to focus on analytics and business value rather than data integration challenges. **How Hiboo Simplifies Mixed Fleet Data:** * **Unified data model**: All equipment data available through consistent API endpoints regardless of brand * **Standardized formats**: Equipment data normalized into common units, timestamps, and structures * **Reliable processing**: Near real-time data processing with consistent availability patterns * **Comprehensive coverage**: Single API access to all your fleet data **Remaining Synchronization Considerations:** * **Data volume management**: Large fleets still generate significant data volumes requiring efficient processing * **Delayed transmissions**: Some equipment may have connectivity delays that affect data freshness * **Time window limits**: API requests limited to 14-day windows requiring batching for historical data **Strategic Approaches:** * **Incremental sync**: Regular collection of recent data changes * **Batch processing**: Scheduled bulk data collection for historical completeness * **Hybrid strategy**: Combining real-time incremental updates with periodic bulk validation ## Initial Data Lake Population ### Complete Historical Data Load **Problem**: You need to populate your data lake with comprehensive historical time-series data for all equipment in your fleet for analytics, machine learning, and compliance requirements. **Solution**: Use systematic bulk data collection with data kind endpoints, implementing batching strategy to handle API limitations. {% openapi src="" path="/v2/fleet/equipments/{id}/{dataKind}" method="get" %} {% endopenapi %} **Implementation strategy:** **1. Equipment and data prioritization:** ``` 1. Get complete equipment list from fleet endpoint 2. Identify critical data kinds required 3. Prioritize by operational importance or analytics requirements ``` **2. Batched historical collection:** ``` Time window: Maximum 14 days per request (API limitation) Processing: Batch requests in 14-day chunks for complete history Error handling: Retry failed batches with exponential backoff Sequencing: Work backwards from recent data to oldest available ``` **Best practices for bulk loading:** * **Batch time windows**: Split historical data collection into 14-day chunks * **Process during off-hours**: Schedule bulk operations during low-activity periods * **Checkpoint progress**: Track completed equipment and date ranges to enable resume on failures **Batching strategy example:** ``` For 1 year of history: - Split into ~26 batches of 14 days each - Process sequentially: most recent → oldest - Track completion: asset_id + date_range + data_kind combinations - Resume capability: restart from last successful batch ``` ### Consolidated Overview Data **Problem**: You need consolidated daily summaries and multiple data types in a single request for reporting dashboards and overview analytics. **Solution**: Use equipment history endpoints for multi-data-type consolidated information. {% openapi src="" path="/v2/fleet/equipments/{id}/history" method="get" %} {% endopenapi %} **What this endpoint provides:** * **Daily operational summaries**: Engine hours, fuel consumption, distances * **Multiple data types**: Positions, fault codes, fuel levels, engine conditions in one response * **Consolidated format**: Pre-aggregated data suitable for overview reporting **Use this approach when:** * **Dashboard population**: Creating fleet overview dashboards * **Reporting summaries**: Generating daily/weekly operational reports * **Multi-data-type collection**: Need several data types simultaneously **Note**: For complete detailed time-series data, use the `/{dataKind}` endpoint described above. ## Incremental Synchronization ### Real-Time Data Sync **Problem**: You need to keep your data lake current with near real-time equipment data for operational dashboards and immediate decision-making. **Solution**: Implement incremental sync using snapshot endpoints combined with targeted historical data collection. {% openapi src="" path="/v2/fleet/equipments/snapshot" method="get" %} {% endopenapi %} **Sync schedule:** **High-frequency sync (every 15-30 minutes):** ``` Target: Current operational status Data: Fleet snapshots, individual equipment snapshots Purpose: Real-time dashboards, operational monitoring Storage: Current state tables, operational data store ``` **Medium-frequency sync (every 2-4 hours):** ``` Target: Recent historical data Data: Last 24-48 hours of detailed data Purpose: Recent trend analysis, operational reporting Storage: Time-series tables, recent activity store ``` ### Delayed Data Recovery **Problem**: Equipment data transmission delays mean your data lake may be missing recent data that arrives later than expected. **Solution**: Implement systematic delayed data recovery using overlapping time windows. **Recovery strategy:** **Weekly validation sync:** ``` Time window: Last 10 days (comprehensive delayed data capture) Schedule: Weekly on weekend nights Process: Full data validation and gap filling Focus: Complete data integrity and weekend transmission delays ``` **Implementation pattern:** ``` 1. Query data lake for existing data in time window 2. Query Hiboo API for same time window 3. Identify gaps and changes 4. Update data lake with missing/updated records 5. Log data quality metrics and delay patterns ``` # Exporting cumulative data to your systems Cumulative counters are essential metrics that track equipment usage over time, providing critical data for maintenance scheduling, cost accounting, and operational analytics. This guide covers the unique challenges and best practices for working with Hiboo's cumulative counter data. ## Overview Cumulative counters differ from other equipment data because they represent running totals that continuously increase throughout an equipment's operational life. Understanding their behavior and implementing proper handling is crucial for reliable business system integration. **How Hiboo Simplifies Counter Management:** * **Standardized counters**: All cumulative data available in consistent formats across equipment brands * **Business-ready values**: Formatted for direct consumption by enterprise systems **Unique Counter Characteristics:** * **Always increasing**: Values should only grow over time (except during resets) * **Reset scenarios**: Counters may reset to zero during maintenance or component replacement * **Threshold significance**: Specific counter values trigger business processes ## Understanding Counter Types ### Operating Time Counters **Cumulative operating hours** track total engine runtime and are fundamental for: * **Depreciation calculations**: Asset value reduction based on usage * **Maintenance scheduling**: Service intervals triggered by hour thresholds * **Rental billing**: Usage-based charging for rental equipment * **Efficiency analysis**: Comparing operational vs idle time {% openapi src="" path="/v2/fleet/equipments/snapshot" method="get" %} {% endopenapi %} ## Counter Reset Scenarios ### Understanding Counter Resets **Problem**: Equipment counters reset to zero during maintenance, component replacement, or system failures, disrupting business processes that depend on continuously increasing values. **Solution**: Implement robust reset detection and handling strategies to maintain data continuity for business systems. **Common reset triggers:** * **Scheduled maintenance**: Engine overhauls or major component replacement * **Component failure**: ECU replacement or system malfunctions * **Software updates**: Firmware updates that clear stored counters * **Battery disconnection**: Power loss that resets electronic systems **Reset detection methods:** **Value decrease detection:** ``` 1. Compare current value with previous reading 2. Identify significant decreases (potential resets) 3. Validate against maintenance records 4. Apply appropriate business system update strategy ``` **Maintenance correlation:** ``` 1. Cross-reference reset events with maintenance schedules 2. Document reset reason codes for audit trails 3. Maintain continuous usage tracking despite resets 4. Preserve historical data integrity ``` ### Business Impact Management **Problem**: Counter resets can disrupt automated billing, maintenance scheduling, and depreciation calculations. **Solution**: Implement business logic that maintains operational continuity despite counter resets. **Continuity strategies:** * **Virtual counters**: Maintain separate running totals that account for resets * **Reset adjustment**: Add reset values to subsequent readings * **Parallel tracking**: Use multiple data sources to validate counter accuracy * **Business rules**: Define how different systems should handle reset scenarios **Example reset handling:** ``` Equipment ABC123 counter reset detected: - Previous reading: 1,247.5 hours - Current reading: 0.0 hours (reset to zero) - Business system action: Add 1,247.5 to all future readings - Maintenance record: Updated with reset event and reason ``` ## Threshold-Based Triggers ### Maintenance Scheduling **Problem**: Business systems need to trigger maintenance actions when equipment counters reach specific thresholds. **Solution**: Implement threshold monitoring that accounts for counter behavior and business requirements. {% openapi src="" path="/v2/fleet/equipments/{id}/{dataKind}" method="get" %} {% endopenapi %} **Threshold implementation:** **Service interval triggers:** ``` Operating hours: Trigger maintenance at 250, 500, 1000 hour intervals Distance milestones: Service alerts at 5,000, 10,000 km intervals Load cycles: Component inspection after 10,000 cycles Specialized systems: PTO hours for auxiliary equipment maintenance ``` **Business system integration:** ``` 1. Monitor counter progression in real-time 2. Calculate time/usage until next threshold 3. Generate advance warnings for maintenance planning 4. Trigger work orders when thresholds are reached 5. Update maintenance schedules after service completion ``` ### Usage-Based Billing **Problem**: Rental and service agreements require accurate usage tracking for billing purposes. **Solution**: Implement precise counter monitoring with appropriate validation and billing integration. **Billing counter applications:** * **Rental equipment**: Hourly charges based on operating time * **Service contracts**: Usage-based maintenance pricing * **Project allocation**: Equipment costs distributed by usage * **Performance contracts**: Billing based on productivity metrics **Billing integration considerations:** ``` Reading frequency: Align with billing periods (daily, weekly, monthly) Validation rules: Ensure counter progression is reasonable Reset handling: Maintain billing continuity despite counter resets Audit trails: Document all counter readings for billing disputes ``` # Hiboo Connect # First share ## Why share your fleet data? For rental companies, sharing fleet data is not just beneficial—it's essential. * **Market demand**: Data sharing is becoming a standard requirement in major tenders, reflecting a clear market trend and ensuring you stay competitive. * **Service differentiation**: Sharing data allows you to build and offer a complementary digital service, setting you apart from the competition and adding value to your offerings. * **Net-Zero transition**: Seamless data flow is crucial for helping the industry meet its net zero goals, contributing to a more sustainable future. * **Ease and control**: Our Sharing API makes the process effortless and secure, giving you complete control over your data-sharing operations with minimal effort. > Data sharing is central to our digital offering. It enables our users to leverage data from their entire operated fleet, boosting productivity and reducing their carbon footprint.\ > — Jérémy F., Purchase Director ## Why do it via API? Data sharing can be created in your Hiboo application, but the Connect API allows you to automate things: * Automating means creating value for your customers, without any extra effort on your part. * Automating means ensuring that the shares you create reflect the contractual commitments you have made to your customers, and how they evolve. Whichever creation method you choose, your customers will be able to benefit from the data shared on their Hiboo application. ## Step by step ### 1. Authentication If you have not done it yet, check the [getting started page about authentication](/guides/getting-started/authenticate-test) ### 2. Create your first data sharing {% openapi src="" path="/sharings" method="post" %} {% endopenapi %} ### 3. Your data is shared! #### Existing beneficiary The equipment you have shared is now available in your beneficiary environment

Illustration of what the beneficiary could see

#### New beneficiary Hiboo team has been notified and will securely set up the connection with the company you are targeting. You have nothing to do, we are on it! # Syncing contracts to automate data sharing Rental businesses often manage hundreds of active contracts with varying equipment assignments, project timelines, and customer requirements. Manual data sharing management becomes inefficient and error-prone at scale. This guide shows how to automate data sharing based on your contract lifecycle. This approach transforms contract events into automated data sharing actions, ensuring your customers always have the right access to the right equipment data at the right time. ## Overview Contract-driven automation synchronizes your business systems with Hiboo's sharing capabilities, creating a seamless flow from contract signature to automatic data access. **Key Benefits:** * **Eliminate manual errors**: Automatically create and manage sharings based on contract data * **Improve customer experience**: Equipment data becomes available immediately when contracts start * **Scale efficiently**: Handle hundreds of simultaneous contracts without manual intervention * **Ensure compliance**: Automatically stop data sharing when contracts end or are terminated **Common Integration Sources:** * **Rental management systems**: Wynne Systems, Point of Rental, Alert EasyPro, RentalMan * **ERP systems**: SAP, Oracle, NetSuite, Microsoft Dynamics * **CRM systems**: Salesforce, HubSpot, custom customer management systems * **Project management tools**: Procore, PlanGrid, custom project systems ## Contract Lifecycle Automation ### New Contract Activation **Problem**: When a rental contract begins, customers need immediate access to their equipment data for project planning and operations monitoring. **Solution**: Automatically create data sharings when contracts are activated in your business system. {% openapi src="" path="/sharings" method="post" %} {% endopenapi %} **Implementation approach:** **Contract event detection:** 1. Monitor your rental system for new active contracts 2. Extract equipment assignments and customer contact information 3. Determine required data packages based on contract type 4. Generate sharing reference using contract identifier **Automated sharing creation:** ``` POST /v2/fleet/sharings { "reference": "CONTRACT-ABC123-2024", "startDate": "2024-01-15T00:00:00Z", "endDate": "2024-06-30T23:59:59Z", "assetIds": [1234, 1235, 1236], "recipient": "projectmanager@customer.com", "notificationEnabled": true, "properties": { "contract": "ABC123", "customer": "ABC Construction", "site": "Highway Project Phase 2", "project": "DOT-2024-015" } } ``` **Key considerations:** * **Reference format**: Use consistent contract-based references for easy tracking * **Customer contacts**: Ensure correct recipient email from your CRM/customer database * **One sharing per asset**: Most customers prefer individual sharings for each piece of equipment to simplify updates and machine swaps **Recommended sharing strategy:** ``` // Instead of one sharing with multiple assets POST /v2/fleet/sharings { "reference": "CONTRACT-ABC123-2024", "assetIds": [1234, 1235, 1236] // Multiple assets } // Create individual sharings for easier management POST /v2/fleet/sharings { "reference": "CONTRACT-ABC123-2024-EXCAVATOR-001", "assetIds": [1234], // Single asset "properties": { "contract": "ABC123", "customer": "ABC Construction", "site": "Highway Project Phase 2", "project": "DOT-2024-015" } } POST /v2/fleet/sharings { "reference": "CONTRACT-ABC123-2024-DOZER-002", "assetIds": [1235], // Single asset "properties": { "contract": "ABC123", "customer": "ABC Construction", "site": "Highway Project Phase 2", "project": "DOT-2024-015" } } ``` ### Contract Modifications **Problem**: Rental contracts frequently change—equipment additions, removals, timeline extensions, or customer contact updates require data sharing adjustments. **Solution**: Automatically update existing sharings when contract modifications occur. {% openapi src="" path="/sharings/{reference}" method="patch" %} {% endopenapi %} **Modification scenarios:** **Equipment changes:** ``` // With one asset per sharing, equipment swaps are simple: // 1. Stop sharing for equipment being returned DELETE /v2/fleet/sharings/CONTRACT-ABC123-2024-EXCAVATOR-001 // 2. Create sharing for replacement equipment POST /v2/fleet/sharings { "reference": "CONTRACT-ABC123-2024-EXCAVATOR-003", "startDate": "2024-01-15T00:00:00Z", "endDate": "2024-06-30T23:59:59Z", "assetIds": [1237], // New replacement excavator "recipient": "projectmanager@customer.com", "notificationEnabled": true, "properties": { "contract": "ABC123", "customer": "ABC Construction", "site": "Highway Project Phase 2", "project": "DOT-2024-015" } } // Other equipment sharings remain unaffected ``` **Benefits of one asset per sharing:** * **Simplified swaps**: Replace individual machines without affecting other equipment access * **Granular control**: Different data packages or access levels per equipment type * **Easier tracking**: Clear audit trail for each piece of equipment * **Reduced errors**: Lower risk of accidentally affecting wrong equipment during updates **Timeline extensions:** ``` PATCH /v2/fleet/sharings/CONTRACT-ABC123-2024 { "endDate": "2024-09-30T23:59:59Z" // Extended project end date } ``` **Contact updates:** ``` PATCH /v2/fleet/sharings/CONTRACT-ABC123-2024 { "properties": { "contract": "ABC123", "customer": "ABC Construction", "site": "Highway Project Phase 2", "project": "DOT-2024-015" } } ``` **Note**: Equipment list changes require recreating the sharing as `assetIds` cannot be modified through PATCH operations. ### Contract Completion **Problem**: When rental contracts end, data access should be terminated promptly to maintain security and comply with data sharing agreements. **Solution**: Automatically stop data sharings when contracts are marked complete or terminated. {% openapi src="" path="/sharings/{reference}" method="delete" %} {% endopenapi %} **Contract completion automation:** ``` 1. Detect contract completion in your rental system 2. Stop active data sharing immediately 3. Update contract status tracking ``` ## Equipment Management Best Practices ### One Asset Per Sharing Strategy **Problem**: Equipment swaps, replacements, and reassignments are common in rental operations, but managing multi-asset sharings makes updates complex and error-prone. **Solution**: Create individual sharings for each piece of equipment to simplify management and reduce operational overhead. **Single-asset sharing approach:** ``` // Create separate sharings for each piece of equipment POST /v2/fleet/sharings { "reference": "CONTRACT-ABC123-2024-EXCAVATOR-001", "assetIds": [1234], // Single excavator "recipient": "projectmanager@customer.com", "startDate": "2024-01-15T00:00:00Z", "endDate": "2024-06-30T23:59:59Z", "properties": { "contract": "ABC123", "customer": "ABC Construction", "site": "Highway Project Phase 2" } } POST /v2/fleet/sharings { "reference": "CONTRACT-ABC123-2024-DOZER-002", "assetIds": [1235], // Single dozer "recipient": "projectmanager@customer.com", "startDate": "2024-01-15T00:00:00Z", "endDate": "2024-06-30T23:59:59Z", "properties": { "contract": "ABC123", "customer": "ABC Construction", "site": "Highway Project Phase 2" } } ``` ### Equipment Swaps and Replacements **Equipment replacement workflow:** ``` // When equipment needs replacement: // 1. Stop sharing for equipment being returned DELETE /v2/fleet/sharings/CONTRACT-ABC123-2024-EXCAVATOR-001 // 2. Create sharing for replacement equipment POST /v2/fleet/sharings { "reference": "CONTRACT-ABC123-2024-EXCAVATOR-003", "assetIds": [1237], // Replacement excavator "recipient": "projectmanager@customer.com", "startDate": "2024-02-01T00:00:00Z", // Swap date "endDate": "2024-06-30T23:59:59Z", "properties": { "contract": "ABC123", "customer": "ABC Construction", "site": "Highway Project Phase 2" } } // All other equipment sharings remain active and unaffected ``` **Benefits of single-asset sharings:** * **Simplified swaps**: Replace individual machines without affecting other equipment * **Granular control**: Different data packages or contact persons per equipment type * **Clear audit trails**: Easy tracking of individual equipment access history * **Reduced errors**: Lower risk of accidentally affecting multiple pieces of equipment * **Faster operations**: Quick equipment changes without complex asset list management ## Implementation Best Practices ### Error Handling and Recovery **Contract synchronization resilience:** * Implement retry logic with exponential backoff for API failures * Maintain synchronization status tracking in your system * Create alerting for failed contract automation * Design rollback procedures for partial failures **Data consistency:** * Verify sharing creation success before marking contracts as "data-enabled" * Implement periodic reconciliation between your system and Hiboo * Handle edge cases like duplicate contracts or overlapping equipment assignments * Log all automation actions for audit and troubleshooting # FAQ & Troubleshooting ## General ### I got an error, what should I do? Don't hesitate to contact us you can refer to our [support page](/guides/how-to-get-help) for the process. ### Is there any rate-limit? No, at this time we do not enforce a rate-limit, but the data will change at most once every 10min. If we encounter any issues or abuse, we may contact you to discuss your specific needs. ### Do you have a Postman collection? Yes, you find all the details in our documentation [here](/guides/getting-started/collections). ## Authentication ### How to get access? If you have an account on production, you will be able to generate credentials on the [Destinations Page](https://app.hiboo.io/destinations) in the Hiboo application. If you have no access to this page, contact us at [support@hiboo.io](mailto:support@hiboo.io?Subject=\[Hiboo%20API]%20Credentials%20Request) ### Does the authentication token expire? * Yes, at the moment it is set to expires after 10 days ## Data freshness ### What is the frequency of the data ? * The amount of data given can vary for a single endpoint depending on the source of the data. One value per day at maximum can be provided for all daily variables (`dailyFuel`, `dailyDistance`...). Multiple values per day can be provided for all other variables (`cumulativeOperatingHours`, `positions`, `cumulativeDistances`...) * Some constructors provide only one cumulative value per day, others can provide up to one value per minute * In our sandbox environment there are less data today. You can expect one data point per day. All data points are not handled too, for instance `CumulativePowerTakeOff` is not yet available. ### What time range can I request ? * For endpoints where dates can be provided as parameters (such as `/equipments/{id}/history`), the maximum possible value is a **14** (fourteen) days period whenever in the past. ### Can data be updated over time, for instance daily data? Does it happen on a fixed schedule? We compute data in near real-time when we receive data. So depending on the data source, it does not happen on a schedule. For instance for a given brand of equipment, we receive data of "Engine off" only when the engine of the machine is turned back on so there can be a delay of a few days, sometime more. With this in mind, an update after 2-3 days is quite typical especially because of the weekend. Today, we recommend to: * Fetch recent data multiple times per day or per hour depending on the use case (either using the snapshot endpoint or a small time span) * Fetch 10 days of data every week in order to catch up any changes ## Data understanding ### There’s daily data but what about timezone? Great question, when we compute daily data (operatingHours, idleHours, fuelUsed...) the timezone of the equipment is taken into consideration. So if you fetch data for `2022-04-20T00:00:00Z`, we should actually only provide `2022-04-20` as the time we consider depends on the geolocation of the equipment. For instance, if an equipment is on the `America/Pacific` timezone, we would consider activity between `2022-04-20T07:00:00Z` and `2022-04-21T06:59:59Z` ## Pagination ### Why are you using paginated endpoints? A paginated endpoint is an endpoint that returns a subset of the data, we are doing so for: * Better Performance – Prevents retrieving too much data at once. * Improved API Efficiency – Reduces load on the server. * Easier Navigation – Fetch data in smaller, manageable chunks. ### How to use paginated endpoints? To get the entire dataset, you need to make multiple requests to the endpoint, each time retrieving a different subset of the data. To do so, you need to use the limit and offset query parameters : limit: it controls the numbers of items returned offset: it controls the number of items to skip before starting to collect the result set # Hiboo Connect ### Can I send any dates? In the future? In the past? As long as you use dates that are in the future everything will be automatically fine. If you use dates in the past (for start date or end date), we will need to reprocess the data, which is a resource-intensive task. Currently, we only process data from the past year. If you have a specific need for this feature, please let us know. ### What happens if I try to create a sharing with an archived asset? Keep in mind we stop updating data for an asset the moment it is archived. You can still create a sharing for this asset though. In this case, only the intersection between the active periods of the asset and the sharing period will be shared with the beneficiary. ### What happens for my beneficiary at the end of a sharing ? Your beneficiary will stop receiving data from the shared assets and those will be archived in his workspace. # Support & Contact ## Contact Support **Email**: * General questions and technical support * Account and billing inquiries * Bug reports and feature requests ## Developer Resources ### Documentation * Check our [FAQ section](/guides/general) for common questions * Review API reference for endpoint details * Browse our [Guides](https://gitlab.com/hiboo.io/sharing-api-doc/-/blob/main/3-guides/README.md) for implementation examples ## Before Contacting Support To help us assist you faster, please include: 1. **API endpoint** you're trying to use 2. **Request/response examples** (remove sensitive data) 3. **Error messages** and status codes 4. **Your environment** (sandbox/production) 5. **Your organization** ## Service Status Check our [status page](https://hiboo.statuspage.io) for: * Current system status * Scheduled maintenance * Recent incidents and updates # Security We care about security. If you have any questions, or encounter any issues, please [contact us](mailto:security@hiboo.io). ## API Security ### Authentication * All API requests require Bearer token authentication * Tokens are JWT-based ### Data Transmission * All API endpoints require HTTPS/TLS 1.2+ * No sensitive data should be transmitted in URL parameters ### Rate Limiting * No strict rate limit is enforced but we are using Web Application Firewall to ensure no DDoS ## Trust Center Please have a look at our [Trust Center](https://trust.hiboo.io/) ## Product Security Product security is of paramount importance at Hiboo. We use a software development lifecycle in line with general Agile principles. When security effort is applied throughout the Agile release cycle, security oriented software defects are able to be discovered and addressed more rapidly than in longer release cycle development methodologies. Software patches are released on an on-going basis as part of our continuous integration and continuous deployment process. Thanks to our continuous integration, we are able to respond rapidly to both functional and security issues. Change management policies and procedures determine when and how changes occur. We are able to achieve extremely short mean time to resolution for security vulnerabilities and functional issues. ## Physical Security ### Cloud Our infrastructure is hosted in Cloud Service Provider (CSP) environments. Physical and environmental security related controls including buildings, locks or keys used on doors, are managed by these CSP’s. "*Physical access is strictly controlled both at the perimeter and at building ingress points by professional security staff. Authorized staff must pass two-factor authentication a minimum of two times to access data center floors."* [*AWS Shared Responsibility Model*](https://aws.amazon.com/compliance/shared-responsibility-model/) Our physical infrastructure is hosted and managed within Amazon’s secure data centers and utilize the Amazon Web Service (AWS) technology. Amazon continually manages risk and undergoes recurring assessments to ensure compliance with industry standards. Amazon’s data center operations have been accredited under: * ISO 27001 * SOC 1 and SOC 2/SSAE 16/ISAE 3402 (Previously SAS 70 Type II) * PCI Level 1 * FISMA Moderate * Sarbanes-Oxley (SOX) For more information, please check [AWS Security Policy](https://aws.amazon.com/security/) ### IoT, Hardware and Network Security and IoT are compatible and they are our priority. We work with hand-picked partners to provide telematics devices when equipment are not natively connected. Some of our partners works with Sigfox network. Thanks to Sigfox dedication to security, our users benefit of data protection in motion via measures built in the protocol (authentication, integrity, encryption, anti-replay, anti-jamming) data protection at rest via cryptographic storage of data and credentials in devices, base stations, and Sigfox Core Network. For more information, please check [Sigfox Security Policy](https://www.sigfox.com/en/technology/security). ## Data Protection ### Authentication and Access Management All requests to the Hiboo Servers must be authenticated and data access is restricted. We work in close relationship with manufacturers and data providers to ensure that security best practices are enforced and that our data exchanges are secured. ### Protection of Customer Data Data submitted to our service by authorized users is considered confidential. This data is protected in transit across public networks. Customer Data is not authorized to exit the Hiboo environment, except in limited circumstances such as in support of a customer request. All data transmitted between Hiboo and Hiboo users is protected using Transport Layer Security (TLS) and HyperText Transfer Protocol Secure (HTTPS). Customer Data currently resides in the European Union in France. Hiboo monitors critical infrastructure for security related events by using both open source and commercial technologies. ### Backup Here is the policy regarding data encryption and backup: > All our production plans are **encrypted at rest with AES-256**, block-level storage encryption. Keys are managed by Amazon, and individual volume keys are stable for the lifetime of the volume. You can find more detail about EBS encryption [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html). All backup files that are taken are stored in an encrypted S3 bucket. > **Data — and any changes made to the database — are continuously and automatically backed up over the last 7 days and a weekly backup kept for a month** ### Audit & Penetration testing We aim at a yearly penetration testing audit by a 3rd party. Our latest one was done on Jan 2025 by Bastion.tech. You can check the audit certification with the link below Our latest report is available on demand at ### Certification We are ISO 27001 certified. ### GDPR You can find more information on our GDPR policy here: [GDPR (RGPD)](https://eu1.hubs.ly/H0lkG3g0) ### OWASP Top 10 [OWASP Top 10](/guides/how-to-get-help/security/owasp) ## People We have dedicated processes and resources to efficiently manage onboarding and off-boarding of employees including: Account configuration, Access definition and control, training on cybersecurity and best practices. We also have an internal IT Charter including our policy on computer usage, mobile devices, password… All our contracts contains legal clauses on privacy and security. ## Report an issue ### Disclosure If you believe you’ve discovered a bug in Hiboo's security, please get in touch at and we will get back to you within 24 hours, and usually earlier. # OWASP The [Open Web Application Security Project](https://www.owasp.org/) (OWASP) maintains a list of what they regard as the [Top 10 Web Application Security Risks](https://www.owasp.org/index.php/OWASP_Top_Ten_Project). These are listed below, together with an explanation of how hiboo deals with them. ## 1. Broken Access Control **Description:** Improper enforcement of user permissions can lead to unauthorized information disclosure, modification, or destruction of data. **Mitigation Strategies:** * All access is denied by default, access control mechanisms are implemented once and re-used. * JWT tokens are invalidated on logout * RBAC is implemented ## **2. Cryptographic Failures (Sensitive Data Exposure)** **Description:** Inadequate protection of sensitive data due to weak cryptographic algorithms or improper implementation. **Mitigation Strategies:** * Use strong, industry-standard encryption algorithms (e.g., AES-256). * All data in transit and at rest are encrypted. * Our databases are encrypted at rest with AES-256, block-level storage encryption. ## **3. Injection** **Description:** Injection flaws, such as SQL, NoSQL, or command injection, occur when untrusted data is sent to an interpreter as part of a query or command. **Mitigation Strategies:** * SQL - Prevented by design: All access is limited to authenticated users and can only be performed through the Hiboo API. Raw SQL is not supported. All requests to the database is made through Hiboo API and we use [Sequelize](https://sequelize.org/), the open-source node.js standard. * OS - There is no shell execution performed from within the application. * **Cross-Site Scripting (XSS).** We use framework that escape XSS by design (React JS) and limit the user input ## 4. Insecure Design **Description:** Insecure design issues arise from a lack of security considerations during the design phase. **Mitigation Strategies:** * We work using agile methodologies allowing us to respond quickly * We perform annual regular security reviews by an external company * We have a continuous security training and awareness programs thanks to Elba ## **5. Security Misconfiguration** **Description:** Security misconfigurations occur when systems are not securely configured, leaving them vulnerable to attacks. **Mitigation Strategies:** * We uses AWS platform and Infrastructure as Code to simplify and minimize the misconfiguration. Our deployment process is automated and only the necessary employees have access to the production environment. * We uses up-to-date XML processors and SOAP 1.2 or higher. We limit the uses of XML in favor of JSON ## **6. Vulnerable and Outdated Components (Using Components with Known Vulnerabilities)** **Description:** Using components with known vulnerabilities can compromise the security of the application. **Mitigation Strategies:** * We periodically remove all unused components and librairies. We update our dependencies periodically and they are installed only from NPM after checking the author. * We use Datadog library monitoring ## **7. Identification and Authentication failure (Broken Authentication)** **Description:** Weak authentication mechanisms can lead to unauthorized access to systems. **Mitigation Strategies:** * We use open-source best practices. Today we use JWT authentication * We enforce password with the following policy: * At least one digit * At least one lowercase letter * At least one uppercase letter * At least one special character * At least 12 characters long * We have a continuous security training and awareness programs thanks to Bastion.tech ## **8. Software and Data Integrity Failures (Insecure Deserialization)** **Description:** Integrity failures occur when code and data are not adequately protected from unauthorized alterations. **Mitigation Strategies:** * We enforce a strict type constraints during deserialization. We log all deserialization exceptions and failures and alert when needed. * We have CI/CD pipelines with build, lint, unit tests, integration tests and E2E tests * All merge requests are reviewed by a peer * We enforce strict access to the code repositories and data stores (MFA and periodic review) ## **9. Security Logging and Monitoring Failures (Insufficient Logging & Monitoring)** **Description:** Insufficient logging and monitoring can prevent the detection of breaches and suspicious activity. **Mitigation Strategies:** * We uses AWS platform for low-level logging and monitoring * All logs are centralized in Datadog to monitor our platform. * Alerting is setup on Datadog for critical events. ## 10. Server Side request Forgery (SSRF) **Description:** SSRF vulnerabilities allow attackers to induce the server to make HTTP requests to arbitrary domains. **Mitigation Strategies:** * Our application is server by Amazon Cloudfront through Cloudflare * We restrict user inputs at the minimum and inputs are validated and sanitized * We implement CORS policy to acceptable domains # Login Use your credentials to generate a temporary token that you use in your requests. ## Authenticate on the API > Authenticate on the API with your credentials to get a token that you can use in your requests. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Login","description":"Use your credentials to generate a temporary token that you use in your requests."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[],"paths":{"/login":{"post":{"operationId":"login","summary":"Authenticate on the API","description":"Authenticate on the API with your credentials to get a token that you can use in your requests.","tags":["Login"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"apiKey":{"type":"string"}}}}}},"responses":{"200":{"description":"Token to use in the other API calls","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string"},"admin":{"type":"boolean"},"firstName":{"type":"string"},"lastName":{"type":"string"},"token":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/401Error"}}}}},"components":{"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}}} ``` # Mixed Fleet Data The following endpoints allow you to retrieve all your Mixed Fleet Data such as positions, daily usages, fault codes, and more. # Snapshot The following endpoints allow you to retrieve the last information available for all data kinds for a specific equipment or the entire fleet. ## Fleet > Returns the last information available for all data kinds for the fleet. This endpoint is paginated. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Snapshot","description":"The following endpoints allow you to retrieve the last information available for all data kinds for a specific equipment or the entire fleet."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"limit":{"name":"limit","in":"query","description":"The numbers of items to return","required":false,"schema":{"type":"integer","format":"int32","default":20,"maximum":50}},"offset":{"name":"offset","in":"query","description":"The number of items to skip before starting to collect the result set","required":false,"schema":{"type":"integer","format":"int32","default":0}},"FilterByInProgressSharing":{"name":"filterByInProgressSharing","in":"query","description":"This parameter allows filtering the equipments based on whether the equipment is currently involved in an in-progress sharing process or not.","required":false,"schema":{"type":"integer"}}},"responses":{"SnapshotOfAllEquipments":{"description":"Snapshot of all devices","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"make":{"type":"string"},"model":{"type":"string"},"serialNumber":{"type":"string"},"pin":{"type":"string","nullable":true,"description":"Product Identification Number"},"vin":{"type":"string","nullable":true,"description":"Vehicle Identification Number"},"cumulativeDistance":{"type":"object","properties":{"date":{"format":"date-time","nullable":true,"type":"string"},"odometer":{"format":"float","nullable":true,"type":"number"}}},"cumulativeFuelUsed":{"type":"object","properties":{"date":{"type":"string","format":"date-time","nullable":true},"fuelUsed":{"type":"number","format":"float"}}},"fuelRemaining":{"type":"object","properties":{"date":{"type":"string","format":"date-time","nullable":true},"percent":{"type":"number","format":"float"}}},"cumulativeOperatingHours":{"type":"object","properties":{"date":{"format":"date-time","nullable":true,"type":"string"},"hour":{"format":"float","nullable":true,"type":"number"},"usageHours":{"description":"deprecated, is the same as hour.","format":"float","nullable":true,"type":"number"}}},"lastPosition":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"Date of the last position"},"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"},"altitude":{"type":"number","format":"float","nullable":true,"description":"Altitude in meters above sea level"},"speed":{"type":"number","format":"float","nullable":true,"description":"Speed in kilometers per hour"},"heading":{"type":"number","format":"float","nullable":true,"description":"Heading/direction in degrees (0-360)"}}},"cumulativeLoadCount":{"type":"object","nullable":true,"properties":{"count":{"type":"integer","format":"int64"},"date":{"type":"string","format":"date-time"}}},"cumulativePayloadTotal":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"payload":{"type":"integer","format":"int64"}}},"cumulativeActiveRegenerationHours":{"type":"object","nullable":true,"properties":{"date":{"format":"date-time","nullable":true,"type":"string"},"hours":{"format":"int64","nullable":true,"type":"integer"}}},"cumulativePowerTakeOffHours":{"type":"object","nullable":true,"properties":{"date":{"format":"date-time","nullable":true,"type":"string"},"hours":{"format":"int64","nullable":true,"type":"integer"}}},"peakDailySpeed":{"type":"object","nullable":true,"properties":{"date":{"format":"date-time","nullable":true,"type":"string"},"speed":{"format":"float","nullable":true,"type":"number"}}},"averageDailyEngineLoadFactor":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"percent":{"type":"number","format":"float"}}},"DEFRemainingRatio":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"percent":{"type":"number","format":"float"}}},"cumulativeIdleHours":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"hours":{"format":"int64","nullable":true,"type":"integer"}}}}}}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/snapshot":{"get":{"operationId":"getFleetEquipmentsSnapshot","summary":"Fleet","description":"Returns the last information available for all data kinds for the fleet. This endpoint is paginated.","tags":["Snapshot"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"search","in":"query","description":"Optional - if provided it will return the equipment with a fleet number or serialNumber matching the parameter","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/FilterByInProgressSharing"}],"responses":{"200":{"$ref":"#/components/responses/SnapshotOfAllEquipments"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Fleet following ISO 15143-3 (AEMP) > Returns the list of all equipments and their latest data. This endpoint is paginated. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Snapshot","description":"The following endpoints allow you to retrieve the last information available for all data kinds for a specific equipment or the entire fleet."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"FilterByInProgressSharing":{"name":"filterByInProgressSharing","in":"query","description":"This parameter allows filtering the equipments based on whether the equipment is currently involved in an in-progress sharing process or not.","required":false,"schema":{"type":"integer"}}},"responses":{"EquipmentsISO15143":{"description":"ISO 15143-3 Fleet Snapshot Response","content":{"application/json":{"schema":{"type":"object","required":["Equipment","Links","snapshotTime","version"],"properties":{"Equipment":{"type":"array","items":{"type":"object","properties":{"EquipmentHeader":{"type":"object","required":["SerialNumber"],"properties":{"UnitInstallDateTime":{"type":"string","nullable":true,"format":"date-time"},"OEMName":{"type":"string"},"Model":{"type":"string"},"EquipmentID":{"type":"string","nullable":true},"SerialNumber":{"type":"string"},"PIN":{"type":"string","nullable":true},"VIN":{"type":"string","nullable":true},"HibooID":{"type":"string"}}},"AverageLoadFactorLast24":{"type":"object","nullable":true,"properties":{"datetime":{"type":"string","format":"date-time"},"Percent":{"type":"number"}}},"Location":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"Latitude":{"type":"number"},"Longitude":{"type":"number"},"Altitude":{"type":"number"},"AltitudeUnits":{"type":"string"}}},"CumulativeActiveRegenerationHours":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"Hour":{"type":"number"}}},"CumulativeIdleHours":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"Hour":{"type":"number"}}},"CumulativeIdleNonOperatingHours":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"Hour":{"type":"number"}}},"CumulativeLoadCount":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"Count":{"type":"number"}}},"CumulativeOperatingHours":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"Hour":{"type":"number"}}},"CumulativePowerTakeOffHours":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"Hour":{"type":"number"}}},"CumulativePayloadTotals":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"PayloadUnits":{"type":"string"},"Payload":{"type":"number"}}},"DEFRemaining":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"Percent":{"type":"number"},"DEFTankCapacityUnits":{"type":"string"},"DEFTankCapacity":{"type":"number"}}},"Distance":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"OdometerUnits":{"type":"string"},"Odometer":{"type":"number"}}},"EngineStatus":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"EngineNumber":{"type":"string","nullable":true},"Running":{"type":"boolean"}}},"FuelUsed":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"FuelUnits":{"type":"string"},"FuelConsumed":{"type":"number"}}},"FuelUsedLast24":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"FuelUnits":{"type":"string"},"FuelConsumed":{"type":"number"}}},"FuelRemaining":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"Percent":{"type":"number"},"FuelTankCapacityUnits":{"type":"string"},"FuelTankCapacity":{"type":"number"}}},"MaximumSpeedLast24":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time"},"SpeedUnits":{"type":"string"},"Speed":{"type":"number"}}}}}},"Links":{"type":"array","items":{"type":"object","required":["rel","href"],"properties":{"rel":{"type":"string","enum":["self","prev","next","last"]},"href":{"type":"string","format":"uri"}}}},"snapshotTime":{"type":"string","format":"date-time"},"version":{"type":"number"}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/iso15143-3/Fleet/{pageNumber}":{"get":{"operationId":"getFleetAEMP","summary":"Fleet following ISO 15143-3 (AEMP)","description":"Returns the list of all equipments and their latest data. This endpoint is paginated.","tags":["Snapshot"],"parameters":[{"name":"pageNumber","in":"path","description":"Page number to retrieve. The page number starts at 1.","required":true,"schema":{"type":"integer","format":"int32","default":1}},{"$ref":"#/components/parameters/FilterByInProgressSharing"}],"responses":{"200":{"$ref":"#/components/responses/EquipmentsISO15143"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Equipment > Returns the last information available for all data kinds for specific equipment ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Snapshot","description":"The following endpoints allow you to retrieve the last information available for all data kinds for a specific equipment or the entire fleet."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"SnapshotOfSpecificEquipment":{"description":"Latest snapshot of the machine","content":{"application/json":{"schema":{"description":"Snapshot of the specified device for all kinds","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string"},"make":{"type":"string"},"model":{"type":"string"},"serialNumber":{"type":"string"},"pin":{"type":"string","nullable":true,"description":"Product Identification Number"},"vin":{"type":"string","nullable":true,"description":"Vehicle Identification Number"},"lastPosition":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"Date of the last position"},"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"},"altitude":{"type":"number","format":"float","nullable":true,"description":"Altitude in meters above sea level"},"speed":{"type":"number","format":"float","nullable":true,"description":"Speed in kilometers per hour"},"heading":{"type":"number","format":"float","nullable":true,"description":"Heading/direction in degrees (0-360)"}}},"cumulativeOperatingHours":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"Date of the last position","nullable":true},"hour":{"nullable":true,"type":"number","format":"float"}}},"cumulativeDistance":{"type":"object","properties":{"date":{"type":"string","format":"date-time","nullable":true},"odometer":{"nullable":true,"type":"number","format":"float"},"unit":{"type":"string"}}},"cumulativeFuelUsed":{"type":"object","properties":{"date":{"type":"string","format":"date-time","nullable":true},"fuelUsed":{"type":"number","format":"float"},"unit":{"type":"string"}}},"cumulativeLoadCount":{"type":"object","nullable":true,"properties":{"count":{"type":"integer","format":"int64"},"date":{"type":"string","format":"date-time"}}},"cumulativePayloadTotal":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"payload":{"type":"integer","format":"int64"}}},"cumulativeActiveRegenerationHours":{"type":"object","nullable":true,"properties":{"date":{"format":"date-time","nullable":true,"type":"string"},"hours":{"format":"int64","nullable":true,"type":"integer"}}},"cumulativePowerTakeOffHours":{"type":"object","nullable":true,"properties":{"date":{"format":"date-time","nullable":true,"type":"string"},"hours":{"format":"int64","nullable":true,"type":"integer"}}},"peakDailySpeed":{"type":"object","nullable":true,"properties":{"date":{"format":"date-time","nullable":true,"type":"string"},"speed":{"format":"float","nullable":true,"type":"number"}}},"averageDailyEngineLoadFactor":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"percent":{"type":"number","format":"float"}}},"DEFRemainingRatio":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"percent":{"type":"number","format":"float"}}},"cumulativeIdleHours":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"hours":{"format":"int64","nullable":true,"type":"integer"}}},"fuelRemaining":{"type":"object","properties":{"date":{"type":"string","format":"date-time","nullable":true},"percent":{"type":"number","format":"float"}}},"engineCondition":{"type":"object","properties":{"date":{"type":"string","format":"date-time","nullable":true},"running":{"type":"boolean"}}},"nextMaintenance":{"type":"object","properties":{"date":{"type":"string","format":"date-time","nullable":false},"nextMaintenanceDate":{"type":"string","format":"date-time","nullable":true},"usageHoursUntilNextMaintenance":{"type":"number","format":"float","nullable":true},"kmUntilNextMaintenance":{"type":"number","format":"float","nullable":true}}},"evBatteryLevel":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"percent":{"type":"number","format":"float"}}},"evBatteryTemperature":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"celsius":{"type":"number","format":"float"}}},"evBatteryHealth":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"percent":{"type":"number","format":"float"}}},"evBatteryVoltage":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"volts":{"type":"number","format":"float"}}},"evBatteryChargingState":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"state":{"type":"string"},"chargingMode":{"type":"string"}}},"evBatteryCurrent":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"amperes":{"type":"number","format":"float"}}},"evChargingRate":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"watts":{"type":"number","format":"float"}}},"evDischargingRate":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"watts":{"type":"number","format":"float"}}},"evBatteryChargeCyclesCount":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"count":{"type":"integer","format":"int64"}}},"evEnergyUsed":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"wattHours":{"type":"number","format":"float"}}},"evEnergyCharged":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date-time"},"wattHours":{"type":"number","format":"float"}}}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/snapshot":{"get":{"operationId":"getFleetEquipmentSnapshotByEquipmentId","summary":"Equipment","description":"Returns the last information available for all data kinds for specific equipment","tags":["Snapshot"],"parameters":[{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"$ref":"#/components/responses/SnapshotOfSpecificEquipment"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` # Time Series The following endpoints allow you to retrieve the data history (positions, daily usages, fault codes...) of a single machine. ## Activity history > Returns all activities (trips/movements) for a specific piece of equipment. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Time Series","description":"The following endpoints allow you to retrieve the data history (positions, daily usages, fault codes...) of a single machine."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"assetId":{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}},"since":{"name":"since","in":"query","required":false,"description":"Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is beginning of yesterday UTC"}},"until":{"name":"until","in":"query","required":false,"description":"Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is end of today UTC"}}},"responses":{"activities":{"description":"Time series of activities for a specific asset","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"dateStart":{"type":"string","format":"date-time","description":"Start date and time of the activity"},"dateStop":{"type":"string","format":"date-time","description":"End date and time of the activity"},"distanceMeters":{"type":"number","format":"float","description":"Distance traveled during the activity in meters"},"averageSpeedKmH":{"type":"number","format":"float","description":"Average speed during the activity in kilometers per hour"},"firstPositionAddress":{"type":"string","description":"Address of the first recorded position"},"lastPositionAddress":{"type":"string","description":"Address of the last recorded position"}}}},"id":{"type":"integer"},"serialNumber":{"type":"string"},"since":{"type":"string","format":"date-time","description":"The since value actually used"},"until":{"type":"string","format":"date-time","description":"The until value actually used"}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/activities":{"get":{"operationId":"getFleetEquipmentActivities","summary":"Activity history","description":"Returns all activities (trips/movements) for a specific piece of equipment.","tags":["Time Series"],"parameters":[{"$ref":"#/components/parameters/assetId"},{"$ref":"#/components/parameters/since"},{"$ref":"#/components/parameters/until"}],"responses":{"200":{"$ref":"#/components/responses/activities"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Fault history > Returns all fault codes for a specific piece of equipment. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Time Series","description":"The following endpoints allow you to retrieve the data history (positions, daily usages, fault codes...) of a single machine."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"assetId":{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}},"since":{"name":"since","in":"query","required":false,"description":"Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is beginning of yesterday UTC"}},"until":{"name":"until","in":"query","required":false,"description":"Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is end of today UTC"}}},"responses":{"faults":{"description":"Time series of fault codes for a specific asset","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"Date and time when the fault was recorded"},"description":{"type":"string","description":"Human-readable description of the fault"},"identifier":{"type":"string","description":"Fault code identifier/label"},"severity":{"type":"integer","description":"Numerical severity level of the fault"},"levelLabel":{"type":"string","description":"Human-readable severity level label"}}}},"id":{"type":"integer"},"serialNumber":{"type":"string"},"since":{"type":"string","format":"date-time","description":"The since value actually used"},"until":{"type":"string","format":"date-time","description":"The until value actually used"}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/faults":{"get":{"operationId":"getFleetEquipmentFaults","summary":"Fault history","description":"Returns all fault codes for a specific piece of equipment.","tags":["Time Series"],"parameters":[{"$ref":"#/components/parameters/assetId"},{"$ref":"#/components/parameters/since"},{"$ref":"#/components/parameters/until"}],"responses":{"200":{"$ref":"#/components/responses/faults"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Position history > Returns all GPS positions for a specific piece of equipment. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Time Series","description":"The following endpoints allow you to retrieve the data history (positions, daily usages, fault codes...) of a single machine."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"assetId":{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}},"since":{"name":"since","in":"query","required":false,"description":"Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is beginning of yesterday UTC"}},"until":{"name":"until","in":"query","required":false,"description":"Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is end of today UTC"}}},"responses":{"positions":{"description":"Time series of positions for a specific asset","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"Date and time when the position was recorded"},"latitude":{"type":"number","format":"float","description":"Latitude coordinate in decimal degrees"},"longitude":{"type":"number","format":"float","description":"Longitude coordinate in decimal degrees"},"altitude":{"type":"number","format":"float","nullable":true,"description":"Altitude in meters above sea level"},"speed":{"type":"number","format":"float","nullable":true,"description":"Speed in kilometers per hour"},"heading":{"type":"number","format":"float","nullable":true,"description":"Heading/direction in degrees (0-360)"}}}},"id":{"type":"integer"},"serialNumber":{"type":"string"},"since":{"type":"string","format":"date-time","description":"The since value actually used"},"until":{"type":"string","format":"date-time","description":"The until value actually used"}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/positions":{"get":{"operationId":"getFleetEquipmentPositions","summary":"Position history","description":"Returns all GPS positions for a specific piece of equipment.","tags":["Time Series"],"parameters":[{"$ref":"#/components/parameters/assetId"},{"$ref":"#/components/parameters/since"},{"$ref":"#/components/parameters/until"}],"responses":{"200":{"$ref":"#/components/responses/positions"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Data kind history > Returns time series data for a specific data kind for a piece of equipment. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Time Series","description":"The following endpoints allow you to retrieve the data history (positions, daily usages, fault codes...) of a single machine."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"assetId":{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}}},"responses":{"SnapshotOfEquipmentDataKind":{"description":"Snapshot of all devices. The shape of each row varies by data kind — this example shows `fuelRemaining`. For `dailyFuel` and `dailyCO2`, rows also include an `estimated` boolean: whether the value was estimated from usage hours × the model's consumption rate, rather than measured from telematics.\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"percent":{"type":"number","format":"float","description":"Percentage of fuel remaining in the asset's tank.\n"},"date":{"type":"string","format":"date-time"}}}},"id":{"type":"integer"},"serialNumber":{"type":"string"},"since":{"type":"string","format":"date-time","description":"The since value actually used"},"until":{"type":"string","format":"date-time","description":"The until value actually used"}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/{dataKind}":{"get":{"operationId":"getFleetEquipmentDataKindByEquipmentId","summary":"Data kind history","description":"Returns time series data for a specific data kind for a piece of equipment.","tags":["Time Series"],"parameters":[{"$ref":"#/components/parameters/assetId"},{"name":"dataKind","in":"path","description":"Data kind identifier.","required":true,"schema":{"type":"string","enum":["activities","averageDailyEngineLoadFactor","batteryLevel","batteryVoltage","cumulativeActiveRegenerationHours","cumulativeDistance","cumulativeFuel","cumulativeIdleFuel","cumulativeIdleHours","cumulativeLoadCount","cumulativeOperatingHours","cumulativePayloadTotal","cumulativePowerTakeOffHours","dailyCO2","dailyDistance","dailyEvEnergyUsed","dailyIdleFuel","dailyLoadCount","dailyPayload","dailyUsages","defRemainingRatio","deviceBatteryLevel","deviceBatteryVoltage","engineCondition","engineCoolantTemperature","engineLoadPercentage","evBatteryChargeCyclesCount","evBatteryCurrent","evBatteryHealth","evBatteryLevel","evBatteryTemperature","evBatteryVoltage","evChargingRate","evChargingState","evDischargingRate","evEnergyCharged","evEnergyUsed faults","fuelRemaining","peakDailySpeed","positions","sensorBoolean","temperature"]}},{"name":"since","in":"query","required":false,"description":"Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is beginning of yesterday UTC"}},{"name":"until","in":"query","required":false,"description":"Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is end of today UTC"}}],"responses":{"200":{"$ref":"#/components/responses/SnapshotOfEquipmentDataKind"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Daily history > Returns comprehensive daily history for a piece of equipment including positions, usage, and fault codes. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Time Series","description":"The following endpoints allow you to retrieve the data history (positions, daily usages, fault codes...) of a single machine."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"assetId":{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}}},"responses":{"EquipmentHistory":{"description":"Specific equipment details with its history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"make":{"type":"string"},"model":{"type":"string"},"serialNumber":{"type":"string"},"pin":{"type":"string","nullable":true,"description":"Product Identification Number"},"vin":{"type":"string","nullable":true,"description":"Vehicle Identification Number"},"positions":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"},"date":{"type":"string","format":"date-time"}}}}}},"faultCodes":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"levelLabel":{"type":"string","nullable":true,"enum":["unknown","information","warning","error","critical"]},"severity":{"type":"number","format":"int64","nullable":true,"enum":[-1,0,1,2],"description":"Severity of the error * -1 - Unknown * 0 - Information * 1 - Warning * 2 - Error\n"},"identifier":{"type":"string"},"description":{"type":"string"},"date":{"type":"string","format":"date-time"}}}}}},"fuelRemainings":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"percent":{"type":"number","format":"float","description":"Perentage of fuel remaining in the asset's tank.\n"},"date":{"type":"string","format":"date-time"}}}}}},"engineConditions":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"running":{"type":"boolean","description":"True if engine went from running to stopped. False if engine went from stopped to running.\n"},"date":{"type":"string","format":"date-time"}}}}}},"dailyUsages":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"operatingHours":{"type":"object","description":"The total number of engine hours on this date","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"idleHours":{"type":"object","description":"The total number of idle engine hours on this date","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"workingHours":{"type":"object","description":"The total number of \"useful\" e.g. non-idle engine hours on this date","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"fuelUsed":{"type":"object","description":"The total of liter of fuel used on this date","properties":{"fuelUsed":{"nullable":true,"type":"number","format":"float"},"unit":{"type":"string"},"estimated":{"nullable":true,"type":"boolean","description":"Whether this value was estimated from usage hours × the model's consumption rate, rather than measured from telematics.\n"}}},"dailyDistance":{"type":"object","description":"Number of kilometers traveled on this date","properties":{"odometer":{"nullable":true,"type":"number","format":"float"},"unit":{"type":"string"}}},"cumulativeIdleHours":{"description":"The last available cumulativeIdleHours of the day or null if none available","type":"object","properties":{"hour":{"type":"number","format":"float","nullable":true}}},"cumulativeOperatingHours":{"description":"The last available cumulativeOperatingHours of the day or null if none available","type":"object","properties":{"hour":{"type":"number","format":"float","nullable":true}}},"cumulativeFuelUsed":{"description":"The last available cumulativeFuelUsed of the day or null if none available","type":"object","properties":{"fuelUsed":{"type":"number","format":"float"},"unit":{"type":"string"}}},"cumulativeDistance":{"description":"The last available cumulativeDistance of the day or null if none available","type":"object","properties":{"odometer":{"type":"number","format":"float"},"unit":{"type":"string"}}},"cumulativeLoadCount":{"description":"The number of cycles performed by the machine.","type":"object","properties":{"count":{"nullable":true,"type":"integer","format":"int64"}}},"cumulativePayloadTotal":{"description":"Total payload lifted, hauled or processed by the machine.","type":"object","properties":{"payload":{"type":"number","format":"float"},"payloadUnit":{"type":"string"}}},"cumulativeActiveRegenerationHours":{"description":"The time when the machine is placed in a non-productive state to complete the regeneration process.","type":"object","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"cumulativePowerTakeOffHours":{"type":"object","description":"The time the power take off was driving an implement such as a mower or sprayer.","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"peakDailySpeed":{"description":"Used to monitor excessive machine speed to identify machine misuse or underuse.","type":"object","properties":{"speed":{"type":"number","format":"float"},"speedUnit":{"type":"string"}}},"averageDailyEngineLoadFactor":{"description":"The percentage calculated as the actual fuel consumed over the previous 24 h period divided by the fuel that would have been consumed during that period if the machine had been continually operated at the engine’s rated output.","type":"object","properties":{"percent":{"type":"number","format":"float"}}},"DEFRemainingRatio":{"type":"object","properties":{"percent":{"type":"number","format":"float","description":"The percent of DEF — Diesel exhaust fluid — remaining is used to schedule DEF delivery to the vehicle"},"tankCapacity":{"type":"number","format":"float","description":"The maximum capacity of the DEF tank."},"tankCapacityUnit":{"type":"string"}}},"co2":{"description":"Total CO2 emitted by the machine.","type":"object","properties":{"weight":{"type":"number","format":"float"},"unit":{"type":"string"},"estimated":{"nullable":true,"type":"boolean","description":"Whether this value was estimated from usage hours × the model's consumption rate, rather than measured from telematics.\n"}}}}}}}}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/history":{"get":{"operationId":"getFleetEquipmentHistoryByEquipmentId","summary":"Daily history","description":"Returns comprehensive daily history for a piece of equipment including positions, usage, and fault codes.","tags":["Time Series"],"parameters":[{"$ref":"#/components/parameters/assetId"},{"name":"since","in":"query","required":false,"description":"Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is beginning of yesterday UTC"}},{"name":"until","in":"query","required":false,"description":"Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is end of today UTC"}}],"responses":{"200":{"$ref":"#/components/responses/EquipmentHistory"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Fleet > ⚠️ This endpoint will be deprecated and should not be used anymore. Returns the list of all equipments and their history (positions, daily usages, fault codes). This endpoint is paginated. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Time Series","description":"The following endpoints allow you to retrieve the data history (positions, daily usages, fault codes...) of a single machine."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"limit":{"name":"limit","in":"query","description":"The numbers of items to return","required":false,"schema":{"type":"integer","format":"int32","default":20,"maximum":50}},"offset":{"name":"offset","in":"query","description":"The number of items to skip before starting to collect the result set","required":false,"schema":{"type":"integer","format":"int32","default":0}}},"responses":{"EquipmentsHistory":{"description":"List of equipment with their history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer","format":"int32"},"since":{"type":"string","format":"date-time","description":"The since value actually used"},"until":{"type":"string","format":"date-time","description":"The until value actually used"},"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"make":{"type":"string"},"model":{"type":"string"},"serialNumber":{"type":"string"},"positions":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"},"date":{"type":"string","format":"date-time"}}}}}},"faultCodes":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"number","format":"int64","nullable":true,"enum":[-1,0,1,2],"description":"Severity of the error * -1 - Unknown * 0 - Information * 1 - Warning * 2 - Error\n"},"identifier":{"type":"string"},"description":{"type":"string"},"date":{"type":"string","format":"date-time"}}}}}},"fuelRemainings":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"percent":{"type":"number","format":"float","description":"Perentage of fuel remaining in the asset's tank.\n"},"date":{"type":"string","format":"date-time"}}}}}},"engineConditions":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"running":{"type":"boolean","description":"True if engine went from running to stopped. False if engine went from stopped to running.\n"},"date":{"type":"string","format":"date-time"}}}}}},"dailyUsages":{"type":"object","properties":{"total":{"type":"number","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"operatingHours":{"type":"object","description":"The total number of engine hours on this date","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"idleHours":{"type":"object","description":"The total number of idle engine hours on this date","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"workingHours":{"type":"object","description":"The total number of \"useful\" e.g. non-idle engine hours on this date","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"fuelUsed":{"type":"object","description":"The total of liter of fuel used on this date","properties":{"fuelUsed":{"nullable":true,"type":"number","format":"float"},"unit":{"type":"string"}}},"dailyDistance":{"type":"object","description":"Number of kilometers traveled on this date","properties":{"odometer":{"nullable":true,"type":"number","format":"float"},"unit":{"type":"string"}}},"cumulativeIdleHours":{"description":"The last available cumulativeIdleHours of the day or null if none available","type":"object","properties":{"hour":{"type":"number","format":"float","nullable":true}}},"cumulativeOperatingHours":{"description":"The last available cumulativeOperatingHours of the day or null if none available","type":"object","properties":{"hour":{"type":"number","format":"float","nullable":true}}},"cumulativeFuelUsed":{"description":"The last available cumulativeFuelUsed of the day or null if none available","type":"object","properties":{"fuelUsed":{"type":"number","format":"float"},"unit":{"type":"string"}}},"cumulativeDistance":{"description":"The last available cumulativeDistance of the day or null if none available","type":"object","properties":{"odometer":{"type":"number","format":"float"},"unit":{"type":"string"}}},"cumulativeLoadCount":{"description":"The number of cycles performed by the machine.","type":"object","properties":{"count":{"nullable":true,"type":"integer","format":"int64"}}},"cumulativePayloadTotal":{"description":"Total payload lifted, hauled or processed by the machine.","type":"object","properties":{"payload":{"type":"number","format":"float"},"payloadUnit":{"type":"string"}}},"cumulativeActiveRegenerationHours":{"description":"The time when the machine is placed in a non-productive state to complete the regeneration process.","type":"object","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"cumulativePowerTakeOffHours":{"type":"object","description":"The time the power take off was driving an implement such as a mower or sprayer.","properties":{"hour":{"nullable":true,"type":"number","format":"float"}}},"peakDailySpeed":{"description":"Used to monitor excessive machine speed to identify machine misuse or underuse.","type":"object","properties":{"speed":{"type":"number","format":"float"},"speedUnit":{"type":"string"}}},"averageDailyEngineLoadFactor":{"description":"The percentage calculated as the actual fuel consumed over the previous 24 h period divided by the fuel that would have been consumed during that period if the machine had been continually operated at the engine’s rated output.","type":"object","properties":{"percent":{"type":"number","format":"float"}}},"DEFRemainingRatio":{"type":"object","properties":{"percent":{"type":"number","format":"float","description":"The percent of DEF — Diesel exhaust fluid — remaining is used to schedule DEF delivery to the vehicle"},"tankCapacity":{"type":"number","format":"float","description":"The maximum capacity of the DEF tank."},"tankCapacityUnit":{"type":"string"}}}}}}}}}}}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/history":{"get":{"deprecated":true,"operationId":"getFleetEquipmentsHistory","summary":"Fleet","description":"⚠️ This endpoint will be deprecated and should not be used anymore. Returns the list of all equipments and their history (positions, daily usages, fault codes). This endpoint is paginated.","tags":["Time Series"],"parameters":[{"name":"since","in":"query","required":false,"description":"Fetch the data since this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is beginning of yesterday UTC"}},{"name":"until","in":"query","required":false,"description":"Fetch the data until this date. Expected format is 'YYYY-MM-DDTHH:mm:ssZ'","schema":{"type":"string","format":"date-time","description":"Default is end of today UTC"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/EquipmentsHistory"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` # Fleet Identity Manage your fleet identity, including equipments, workspaces, and custom fields. # Fleet The following endpoints allow you to retrieve the list of all equipments and manage their identity. ## Fleet > Returns the list of all equipments and their identity. This endpoint is paginated. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Fleet","description":"The following endpoints allow you to retrieve the list of all equipments and manage their identity."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"limit":{"name":"limit","in":"query","description":"The numbers of items to return","required":false,"schema":{"type":"integer","format":"int32","default":20,"maximum":50}},"offset":{"name":"offset","in":"query","description":"The number of items to skip before starting to collect the result set","required":false,"schema":{"type":"integer","format":"int32","default":0}},"includeCustomFields":{"name":"includeCustomFields","in":"query","description":"By default, customFields are not included. If set to one, the custom fields will be included in the response","required":false,"schema":{"type":"integer","format":"int32","default":0}},"includeDataSources":{"name":"includeDataSources","in":"query","description":"By default, data sources related to the equipment are not included. If set to one, the data sources will be included in the response","required":false,"schema":{"type":"integer","format":"int32","default":0}},"includeGroup":{"name":"includeGroup","in":"query","description":"By default, equipment group information is not included. If set to one, the group information will be included in the response","required":false,"schema":{"type":"integer","format":"int32","default":0}},"FilterByInProgressSharing":{"name":"filterByInProgressSharing","in":"query","description":"This parameter allows filtering the equipments based on whether the equipment is currently involved in an in-progress sharing process or not.","required":false,"schema":{"type":"integer"}}},"responses":{"Equipments":{"description":"List of equipment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"make":{"type":"string"},"model":{"type":"string"},"serialNumber":{"type":"string"},"pin":{"type":"string","nullable":true,"description":"Product Identification Number"},"vin":{"type":"string","nullable":true,"description":"Vehicle Identification Number"},"workspaces":{"type":"array","items":{"type":"string"}},"customFields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"group":{"type":"object","properties":{"id":{"type":"integer"},"assetIds":{"type":"array","items":{"type":"integer"}}}}}}}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments":{"get":{"operationId":"getFleetEquipments","summary":"Fleet","description":"Returns the list of all equipments and their identity. This endpoint is paginated.","tags":["Fleet"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/includeCustomFields"},{"$ref":"#/components/parameters/includeDataSources"},{"$ref":"#/components/parameters/includeGroup"},{"$ref":"#/components/parameters/FilterByInProgressSharing"}],"responses":{"200":{"$ref":"#/components/responses/Equipments"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Archived Equipments > Returns the list of archived equipments. This endpoint is paginated. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Fleet","description":"The following endpoints allow you to retrieve the list of all equipments and manage their identity."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"limit":{"name":"limit","in":"query","description":"The numbers of items to return","required":false,"schema":{"type":"integer","format":"int32","default":20,"maximum":50}},"offset":{"name":"offset","in":"query","description":"The number of items to skip before starting to collect the result set","required":false,"schema":{"type":"integer","format":"int32","default":0}}},"responses":{"Archived":{"description":"List of archived equipment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"archiveComment":{"type":"string","description":"A comment about why the equipment was archived"},"archiveDate":{"type":"string","description":"The date at which the equipment was last archived serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ)","format":"date-time"}}}}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/archived":{"get":{"operationId":"getArchivedFleetEquipments","summary":"Archived Equipments","description":"Returns the list of archived equipments. This endpoint is paginated.","tags":["Fleet"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"$ref":"#/components/responses/Archived"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Equipment > Returns the identity of the requested equipment ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Fleet","description":"The following endpoints allow you to retrieve the list of all equipments and manage their identity."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"includeCustomFields":{"name":"includeCustomFields","in":"query","description":"By default, customFields are not included. If set to one, the custom fields will be included in the response","required":false,"schema":{"type":"integer","format":"int32","default":0}}},"responses":{"Equipment":{"description":"List of equipment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"make":{"type":"string"},"model":{"type":"string"},"serialNumber":{"type":"string"},"pin":{"type":"string","nullable":true,"description":"Product Identification Number"},"vin":{"type":"string","nullable":true,"description":"Vehicle Identification Number"},"workspaces":{"type":"array","items":{"type":"string"}},"customFields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}":{"get":{"operationId":"getFleetEquipment","summary":"Equipment","description":"Returns the identity of the requested equipment","tags":["Fleet"],"parameters":[{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}},{"$ref":"#/components/parameters/includeCustomFields"}],"responses":{"200":{"$ref":"#/components/responses/Equipment"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Delete an equipment > Marks the specified equipment as deleted. The equipment must be archived before it can be mark as deleted. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Fleet","description":"The following endpoints allow you to retrieve the list of all equipments and manage their identity."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}":{"delete":{"operationId":"deleteFleetEquipment","summary":"Delete an equipment","description":"Marks the specified equipment as deleted. The equipment must be archived before it can be mark as deleted.","tags":["Fleet"],"parameters":[{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"204":{"description":"Equipment deleted successfully (no content)"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"409":{"description":"Equipment cannot be deleted unless it is archived first, or if it is currently involved in an in progress sharing process."}}}}}} ``` ## Get equipment status > Returns the current status of the specified equipment. The response includes metadata depending on the status ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Fleet","description":"The following endpoints allow you to retrieve the list of all equipments and manage their identity."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/status":{"get":{"operationId":"getFleetEquipmentStatus","summary":"Get equipment status","description":"Returns the current status of the specified equipment. The response includes metadata depending on the status","tags":["Fleet"],"parameters":[{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Equipment status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["archived","deleted","active"],"description":"Current status of the equipment"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata depending on the status","properties":{"date":{"type":"string","format":"date-time","description":"Timestamp when the status change occurred"},"comment":{"type":"string","description":"Comment associated with archiving (only present if status is archived)"}}}},"required":["status"]}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"}}}}}} ``` ## Archive an equipment > Marks the specified equipment as archived. Archived equipment will no longer be active, but can be restored later using the \`/status/active\` endpoint. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Fleet","description":"The following endpoints allow you to retrieve the list of all equipments and manage their identity."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/status/archived":{"post":{"operationId":"archiveFleetEquipment","summary":"Archive an equipment","description":"Marks the specified equipment as archived. Archived equipment will no longer be active, but can be restored later using the `/status/active` endpoint.","tags":["Fleet"],"parameters":[{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["comment"],"properties":{"comment":{"type":"string","description":"Reason or note for archiving the equipment"}}}}}},"responses":{"204":{"description":"Equipment archived successfully (no content)"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"409":{"description":"Equipment must be active before it can be archived"}}}}}} ``` ## Unarchive an equipment > Restores a previously archived equipment to active status. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Fleet","description":"The following endpoints allow you to retrieve the list of all equipments and manage their identity."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/status/active":{"post":{"operationId":"unarchiveFleetEquipment","summary":"Unarchive an equipment","description":"Restores a previously archived equipment to active status.","tags":["Fleet"],"parameters":[{"name":"id","in":"path","description":"ID of the equipment","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"204":{"description":"Equipment unarchived successfully (no content)"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"409":{"description":"Equipment must be archived before it can be unarchived"}}}}}} ``` # Workspaces The following endpoints allow you to retrieve the list of all workspaces available and manage the link between equipments and workspaces. ## Workspaces > Returns the list of all workspaces available ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Workspaces","description":"The following endpoints allow you to retrieve the list of all workspaces available and manage the link between equipments and workspaces."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"Workspaces":{"description":"List of equipment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer","format":"int64"},"rows":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"}}}}}}}}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/workspaces":{"get":{"operationId":"getFleetWorkspaces","summary":"Workspaces","description":"Returns the list of all workspaces available","tags":["Workspaces"],"responses":{"200":{"$ref":"#/components/responses/Workspaces"},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Add Equipment to Workspaces > Add asset workspaces data with assetId or (serialNumber AND make) of Asset and workspace names ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Workspaces","description":"The following endpoints allow you to retrieve the list of all workspaces available and manage the link between equipments and workspaces."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"bodyAssetWorkspaceNames":{"type":"object","properties":{"assetId":{"type":"number"},"serialNumber":{"type":"string"},"make":{"type":"string"},"workspaceNames":{"type":"array","items":{"type":"string"}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"400Error":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces":{"post":{"operationId":"linkAssetToWorkspaces","summary":"Add Equipment to Workspaces","description":"Add asset workspaces data with assetId or (serialNumber AND make) of Asset and workspace names","tags":["Workspaces"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/bodyAssetWorkspaceNames"}}}},"responses":{"200":{"description":"Equipment has been added","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/400Error"},"401":{"$ref":"#/components/responses/401Error"},"500":{"description":"An error occurred while processing the request","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}}}}}}} ``` ## Remove Equipment from Workspaces > delete link asset and workspaces data with assetId or (serialNumber AND make) of Asset and workspace names ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Workspaces","description":"The following endpoints allow you to retrieve the list of all workspaces available and manage the link between equipments and workspaces."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"bodyAssetWorkspaceNames":{"type":"object","properties":{"assetId":{"type":"number"},"serialNumber":{"type":"string"},"make":{"type":"string"},"workspaceNames":{"type":"array","items":{"type":"string"}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"400Error":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/equipment/assetWorkspaces/linkAssetToWorkspaces":{"delete":{"operationId":"deleteLinkAssetToWorkspaces","summary":"Remove Equipment from Workspaces","description":"delete link asset and workspaces data with assetId or (serialNumber AND make) of Asset and workspace names","tags":["Workspaces"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/bodyAssetWorkspaceNames"}}}},"responses":{"200":{"description":"Equipment has been unlink between asset and workspace","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/400Error"},"401":{"$ref":"#/components/responses/401Error"},"500":{"description":"An error occurred while processing the request","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}}}}}}} ``` # Equipment Identity The following endpoints allow you to manage the identity of your equipments, such as enterprise, year, model, and custom fields. ## Update Equipment Identity > Update equipment data with assetId or (serialNumber AND make) ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Identity","description":"The following endpoints allow you to manage the identity of your equipments, such as enterprise, year, model, and custom fields."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"asset":{"type":"object","properties":{"assetId":{"type":"number"},"serialNumber":{"type":"string"},"make":{"type":"string"},"name":{"type":"string"},"category":{"type":"string","description":"The category must exist beforehand and will not be created if it does not exist"},"model":{"type":"string"},"entreprise":{"type":"string"},"year":{"oneOf":[{"type":"number"}]}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"400Error":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/equipment":{"patch":{"operationId":"updateFleetEquipment","summary":"Update Equipment Identity","description":"Update equipment data with assetId or (serialNumber AND make)","tags":["Equipment Identity"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/asset"}}}},"responses":{"200":{"description":"Equipment has been modified","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/400Error"},"401":{"$ref":"#/components/responses/401Error"},"500":{"description":"An error occurred while processing the request","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}}}}}}} ``` ## Add Custom Fields to Equipment > add assetCustomFields data with assetId or (serialNumber AND make) ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Identity","description":"The following endpoints allow you to manage the identity of your equipments, such as enterprise, year, model, and custom fields."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"bodyAssetCustomFields":{"type":"object","properties":{"assetId":{"type":"number"},"serialNumber":{"type":"string"},"make":{"type":"string"},"customFields":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"]}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"400Error":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/equipment/assetCustomFields":{"post":{"operationId":"addFleetEquipmentAssetCustomFields","summary":"Add Custom Fields to Equipment","description":"add assetCustomFields data with assetId or (serialNumber AND make)","tags":["Equipment Identity"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/bodyAssetCustomFields"}}}},"responses":{"200":{"description":"AssetCustomFields has been added","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/400Error"},"401":{"$ref":"#/components/responses/401Error"},"500":{"description":"An error occurred while processing the request","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}}}}}}} ``` ## Remove Custom Fields from Equipment > delete assetCustomFields data with assetId or (serialNumber AND make) ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Identity","description":"The following endpoints allow you to manage the identity of your equipments, such as enterprise, year, model, and custom fields."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"bodyAssetCustomFields":{"type":"object","properties":{"assetId":{"type":"number"},"serialNumber":{"type":"string"},"make":{"type":"string"},"customFields":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"required":["label","value"]}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"400Error":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/equipment/assetCustomFields":{"delete":{"operationId":"deleteFleetEquipmentAssetCustomFields","summary":"Remove Custom Fields from Equipment","description":"delete assetCustomFields data with assetId or (serialNumber AND make)","tags":["Equipment Identity"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/bodyAssetCustomFields"}}}},"responses":{"200":{"description":"AssetCustomFields has been deleted","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/400Error"},"401":{"$ref":"#/components/responses/401Error"},"500":{"description":"An error occurred while processing the request","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}}}}}}}}}}} ``` # Equipment Documents The following endpoints allow you to manage documents related to your equipments, including uploading, updating, and deleting documents. ## Get documents for a specific equipment > Retrieve a list of documents for the specified equipment. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Documents","description":"The following endpoints allow you to manage documents related to your equipments, including uploading, updating, and deleting documents."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"parameters":{"offset":{"name":"offset","in":"query","description":"The number of items to skip before starting to collect the result set","required":false,"schema":{"type":"integer","format":"int32","default":0}}},"schemas":{"Document":{"required":["id","name","shareable","isPublic","expirationDate","uploadDate","fileInfos"],"type":"object","properties":{"id":{"type":"number","description":"The unique identifier of the document"},"name":{"type":"string","description":"The name of the document"},"shareable":{"type":"boolean","description":"Indicates whether the document can be shared along with the related equipment. If true, the document will be shared automatically when the equipment is shared; if false, the document remains private."},"isPublic":{"type":"boolean","description":"Indicates whether the document can be publicly accessible."},"expirationDate":{"type":"string","description":"Date when the document becomes invalid, formatted as 'YYYY-MM-DD' in UTC.","format":"date","pattern":"/^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$/"},"fileInfos":{"type":"object","description":"Metadata about the file","properties":{"size":{"type":"number","description":"The size of the file in kB (e.g., 2 for a 2kB file)."},"contentType":{"type":"string","description":"The MIME type of the file (e.g., `application/pdf`, `image/jpeg`, `image/png`)."},"uploadDate":{"type":"string","description":"The date and time when the document was uploaded, serialized as an ISO 8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ).","format":"date-time"}}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"400Error":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/equipments/{id}/documents":{"get":{"summary":"Get documents for a specific equipment","description":"Retrieve a list of documents for the specified equipment.","tags":["Equipment Documents"],"operationId":"listDocuments","parameters":[{"name":"id","description":"The unique identifier of the equipment.","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/offset"},{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","description":"The number of items to return"}}],"responses":{"200":{"description":"A paginated list of documents for the equipment","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of documents for the equipment"},"offset":{"type":"integer","description":"The number of items skipped"},"limit":{"type":"integer","description":"The number of items returned"},"rows":{"type":"array","description":"The list of documents","items":{"$ref":"#/components/schemas/Document"}}}}}}},"400":{"$ref":"#/components/responses/400Error"},"401":{"$ref":"#/components/responses/401Error"},"404":{"$ref":"#/components/responses/404Error"}}}}}} ``` ## Upload a document for a specific equipment > Upload a document to be associated with the specified equipment. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Documents","description":"The following endpoints allow you to manage documents related to your equipments, including uploading, updating, and deleting documents."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"UploadDocumentBody":{"required":["file","name"],"type":"object","properties":{"name":{"type":"string","description":"The name of the document."},"file":{"type":"string","format":"binary","description":"The document file to be uploaded. The document must be one of the following types PDF, JPEG, PNG, GIF, TIFF, Excel, or Word documents. File size should not exceed 10MB (10,485,760 bytes)."},"shareable":{"type":"boolean","description":"Indicates whether the document can be shared along with the related equipment. If true, the document will be shared automatically when the equipment is shared; if false, the document remains private.","default":false},"isPublic":{"type":"boolean","description":"Indicates whether the document can be publicly accessible.","default":false},"expirationDate":{"type":"string","description":"Date when the document becomes invalid, formatted as 'YYYY-MM-DD' in UTC.","format":"date","pattern":"/^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$/"}}},"Document":{"required":["id","name","shareable","isPublic","expirationDate","uploadDate","fileInfos"],"type":"object","properties":{"id":{"type":"number","description":"The unique identifier of the document"},"name":{"type":"string","description":"The name of the document"},"shareable":{"type":"boolean","description":"Indicates whether the document can be shared along with the related equipment. If true, the document will be shared automatically when the equipment is shared; if false, the document remains private."},"isPublic":{"type":"boolean","description":"Indicates whether the document can be publicly accessible."},"expirationDate":{"type":"string","description":"Date when the document becomes invalid, formatted as 'YYYY-MM-DD' in UTC.","format":"date","pattern":"/^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$/"},"fileInfos":{"type":"object","description":"Metadata about the file","properties":{"size":{"type":"number","description":"The size of the file in kB (e.g., 2 for a 2kB file)."},"contentType":{"type":"string","description":"The MIME type of the file (e.g., `application/pdf`, `image/jpeg`, `image/png`)."},"uploadDate":{"type":"string","description":"The date and time when the document was uploaded, serialized as an ISO 8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ).","format":"date-time"}}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"400Error":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/equipments/{id}/documents":{"post":{"summary":"Upload a document for a specific equipment","description":"Upload a document to be associated with the specified equipment.","tags":["Equipment Documents"],"operationId":"uploadDocument","parameters":[{"name":"id","description":"The unique identifier of the equipment.","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"More information about the required payload","required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadDocumentBody"},"encoding":{"file":{"contentType":"application/pdf, image/jpeg, image/png, image/gif, image/tiff, text/csv, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document"}}}}},"responses":{"201":{"description":"Document successfully uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"$ref":"#/components/responses/400Error"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"409":{"description":"Conflict with existing document metadata (e.g., duplicate name)"},"413":{"description":"Payload Too Large. File should not exceeds 10MB"},"415":{"description":"Unsupported Media Type"}}}}}} ``` ## Delete a specific document > Deletes a specific document associated with the specified equipment. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Documents","description":"The following endpoints allow you to manage documents related to your equipments, including uploading, updating, and deleting documents."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/documents/{documentId}":{"delete":{"summary":"Delete a specific document","description":"Deletes a specific document associated with the specified equipment.","tags":["Equipment Documents"],"operationId":"deleteDocument","parameters":[{"name":"id","description":"The unique identifier of the equipment.","in":"path","required":true,"schema":{"type":"integer"}},{"name":"documentId","description":"The unique identifier of the document.","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Document successfully deleted"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"}}}}}} ``` ## Update document metadata > Update the metadata (e.g., name, isPublic) of a specific document associated with the specified equipment. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Documents","description":"The following endpoints allow you to manage documents related to your equipments, including uploading, updating, and deleting documents."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"PatchDocumentBody":{"type":"object","properties":{"name":{"type":"string","description":"The name of the document."},"expirationDate":{"type":"string","description":"Date when the document becomes invalid, formatted as 'YYYY-MM-DD' in UTC.","format":"date","pattern":"/^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$/"}}},"Document":{"required":["id","name","shareable","isPublic","expirationDate","uploadDate","fileInfos"],"type":"object","properties":{"id":{"type":"number","description":"The unique identifier of the document"},"name":{"type":"string","description":"The name of the document"},"shareable":{"type":"boolean","description":"Indicates whether the document can be shared along with the related equipment. If true, the document will be shared automatically when the equipment is shared; if false, the document remains private."},"isPublic":{"type":"boolean","description":"Indicates whether the document can be publicly accessible."},"expirationDate":{"type":"string","description":"Date when the document becomes invalid, formatted as 'YYYY-MM-DD' in UTC.","format":"date","pattern":"/^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$/"},"fileInfos":{"type":"object","description":"Metadata about the file","properties":{"size":{"type":"number","description":"The size of the file in kB (e.g., 2 for a 2kB file)."},"contentType":{"type":"string","description":"The MIME type of the file (e.g., `application/pdf`, `image/jpeg`, `image/png`)."},"uploadDate":{"type":"string","description":"The date and time when the document was uploaded, serialized as an ISO 8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ).","format":"date-time"}}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"400Error":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/equipments/{id}/documents/{documentId}":{"patch":{"summary":"Update document metadata","description":"Update the metadata (e.g., name, isPublic) of a specific document associated with the specified equipment.","tags":["Equipment Documents"],"operationId":"updateDocument","parameters":[{"name":"id","description":"The unique identifier of the equipment.","in":"path","required":true,"schema":{"type":"integer"}},{"name":"documentId","in":"path","description":"The unique identifier of the document.","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"Update an existing document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDocumentBody"}}},"required":true},"responses":{"200":{"description":"Document metadata successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"$ref":"#/components/responses/400Error"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"409":{"description":"Conflict with existing document metadata (e.g., duplicate name)"}}}}}} ``` ## Download a specific document > Allows the user to download a specific document associated with the specified equipment. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Documents","description":"The following endpoints allow you to manage documents related to your equipments, including uploading, updating, and deleting documents."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/equipments/{id}/documents/{documentId}/download":{"get":{"summary":"Download a specific document","description":"Allows the user to download a specific document associated with the specified equipment.","tags":["Equipment Documents"],"operationId":"downloadDocument","parameters":[{"name":"id","description":"The unique identifier of the equipment.","in":"path","required":true,"schema":{"type":"integer"}},{"name":"documentId","description":"The unique identifier of the document.","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Document successfully downloaded","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/401Error"},"404":{"$ref":"#/components/responses/404Error"}}}}}} ``` # Equipment Groups The following endpoints allow you to manage equipment groups, enabling you to link multiple equipments together. ## Create a new equipment group > Create a new group by linking multiple equipments together. At least 2 equipment IDs are required. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Groups","description":"The following endpoints allow you to manage equipment groups, enabling you to link multiple equipments together."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"CreateGroupBody":{"required":["assetIds"],"type":"object","properties":{"assetIds":{"type":"array","description":"List of equipment IDs to group together. At least 2 equipment IDs are required.","minItems":2,"items":{"type":"integer"}}}},"GroupBodySerialized":{"required":["id","assetIds"],"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the group"},"assetIds":{"type":"array","description":"List of equipment IDs in the group","items":{"type":"integer"}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"201":{"description":"Group successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupBodySerialized"}}}},"400":{"description":"Cannot create a group with less than two equipments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permissions to create a group with these equipments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"409":{"description":"One or more equipments are already part of a group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/groups":{"post":{"summary":"Create a new equipment group","description":"Create a new group by linking multiple equipments together. At least 2 equipment IDs are required.","tags":["Equipment Groups"],"operationId":"createGroup","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGroupBody"}}}},"responses":{"201":{"$ref":"#/components/responses/201"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403"},"409":{"$ref":"#/components/responses/409"}}}}}} ``` ## Update an equipment group > Update an existing equipment group by replacing the list of equipments. At least 2 equipment IDs are required. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Groups","description":"The following endpoints allow you to manage equipment groups, enabling you to link multiple equipments together."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"CreateGroupBody":{"required":["assetIds"],"type":"object","properties":{"assetIds":{"type":"array","description":"List of equipment IDs to group together. At least 2 equipment IDs are required.","minItems":2,"items":{"type":"integer"}}}},"GroupBodySerialized":{"required":["id","assetIds"],"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the group"},"assetIds":{"type":"array","description":"List of equipment IDs in the group","items":{"type":"integer"}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/groups/{id}":{"put":{"summary":"Update an equipment group","description":"Update an existing equipment group by replacing the list of equipments. At least 2 equipment IDs are required.","tags":["Equipment Groups"],"operationId":"updateGroup","parameters":[{"name":"id","description":"The unique identifier of the group to update.","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGroupBody"}}}},"responses":{"200":{"description":"Group successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupBodySerialized"}}}},"400":{"description":"Insufficient equipments to form a group (at least 2 required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"description":"Insufficient permissions to edit this group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404":{"description":"Group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"409":{"description":"One or more equipments are already part of another group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` ## Delete an equipment group > Delete an existing equipment group. This will unlink all equipments from the group. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Equipment Groups","description":"The following endpoints allow you to manage equipment groups, enabling you to link multiple equipments together."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/v2/fleet/groups/{id}":{"delete":{"summary":"Delete an equipment group","description":"Delete an existing equipment group. This will unlink all equipments from the group.","tags":["Equipment Groups"],"operationId":"deleteGroup","parameters":[{"name":"id","description":"The unique identifier of the group to delete.","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Group successfully deleted"},"401":{"$ref":"#/components/responses/401Error"},"403":{"description":"Insufficient permissions to delete this group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}}}}} ``` # Hiboo Connect The following endpoints allow you to share your equipment data with other organizations, and manage the sharing process. ## List Sharing > Returns all Sharing instances that have been created ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Hiboo Connect","description":"The following endpoints allow you to share your equipment data with other organizations, and manage the sharing process."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"Sharing":{"required":["reference","startDate","dataPacksCodes","assetIds","recipient","notificationEnabled","properties"],"type":"object","properties":{"reference":{"type":"string","description":"It can be a contract reference for instance"},"startDate":{"description":"Date from which the sharing of data should start serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ).","type":"string","format":"date-time"},"endDate":{"description":"Date when the sharing of data should stop serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). Equipment data will be shared as long as it is empty, so you can set it to `null` if the end date is unsure","type":"string","format":"date-time"},"status":{"description":"Current status of the sharing:\n- pending: The beneficiary user has not yet created an organization in Hiboo\n- planned: The sharing will be active (\"in progress\" status) as soon as the start date is reached\n- in_progress: The sharing is in progress and the beneficiary users have access to the assets data stream\n- stopped: The sharing has been stopped before the initially scheduled end date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history\n- completed: The sharing has ended on the scheduled date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history\n","type":"string","enum":["pending","planned","in_progress","stopped","completed"]},"dataPacksCodes":{"description":"List of data packs shared","type":"array","minItems":0,"items":{"type":"string","enum":["essential","vehicle_conditions","energy_and_fuel","activity","others","usage_hours","fault_codes"]}},"assetIds":{"description":"All the equipment that you wish to share, use Hiboo's ids","type":"array","minItems":1,"items":{"type":"number","format":"int32"}},"recipient":{"description":"Recipient's email address","type":"string","format":"email"},"notificationEnabled":{"description":"Defines if the notification is enabled on the sharing creation/start actions","type":"boolean"},"properties":{"type":"object","description":"Additional properties of the sharing","properties":{"customer":{"type":"string","description":"Customer name"},"site":{"type":"string","description":"Site name"},"contract":{"type":"string","description":"Contract reference"},"purchaseOrder":{"type":"string","description":"Purchase order reference"},"project":{"type":"string","description":"Project reference"},"accountNumber":{"type":"string","description":"Account number"}}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/sharings":{"get":{"tags":["Hiboo Connect"],"summary":"List Sharing","description":"Returns all Sharing instances that have been created","operationId":"listSharing","parameters":[{"name":"offset","in":"query","required":true,"schema":{"type":"integer","description":"The number of items to skip before starting to collect the result set"}},{"name":"limit","in":"query","required":true,"schema":{"type":"integer","description":"The number of items to return"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","planned","in_progress","stopped","completed"]},"description":"Filter by sharing status"},{"name":"assetId","in":"query","required":false,"schema":{"type":"integer","description":"Filter by asset ID"}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sharing"}}}},"400":{"description":"Invalid input or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401Error"}}}}}} ``` ## Create a new Sharing > This endpoint will allow you to create a new instance of Sharing. It can be a contract for instance. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Hiboo Connect","description":"The following endpoints allow you to share your equipment data with other organizations, and manage the sharing process."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"CreateSharingBody":{"required":["reference","startDate","endDate","assetIds","recipient"],"type":"object","properties":{"reference":{"type":"string","description":"It can be a contract reference for instance"},"startDate":{"description":"Date from which the sharing of data should start serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). The date must not be before one rolling year.","type":"string","format":"date-time"},"endDate":{"description":"Date when the sharing of data should stop serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). Equipment data will be shared as long as it is empty, set it to `null` if the end date is unsure","type":"string","format":"date-time"},"optionalDataPackCodes":{"deprecated":true,"description":"**Deprecated.** Use `excludedDataPackCodes` instead. An optional list of data packs to share. If not specified, all data will be shared by default. If set to an empty list, only base data will be shared. Otherwise, base data and specified optional data packs will be shared. If both `optionalDataPackCodes` and `excludedDataPackCodes` are provided, `excludedDataPackCodes` will take precedence and `optionalDataPackCodes` will be ignored. idle data pack is always provided when passing optionalDataPackCodes, even if not specified, to avoid retrocompability issues. To exclude it, use excludedDataPackCodes parameter instead.","type":"array","minItems":0,"items":{"type":"string","enum":["fault_codes"]}},"excludedDataPackCodes":{"description":"An optional list of data packs to exclude from sharing. If not specified, all data will be shared by default. If set to an empty list, no data pack will be excluded. Otherwise, specified data packs will be excluded from sharing.","type":"array","minItems":0,"items":{"type":"string","enum":["fault_codes","idle"]}},"assetIds":{"description":"All the equipment that you wish to share, use Hiboo's ids","type":"array","minItems":1,"items":{"type":"number","format":"int32"}},"recipient":{"description":"Recipient's email address. The local part of the email address can only contain alphanumeric characters and the characters _ ' + - and .","type":"string","format":"email"},"notificationEnabled":{"description":"If false, the recipient will not be notified when the sharing is created or started","type":"boolean"},"properties":{"type":"object","description":"Additional properties to be added to the sharing","properties":{"customer":{"type":"string","description":"Customer name"},"site":{"type":"string","description":"Site name"},"contract":{"type":"string","description":"Contract reference"},"purchaseOrder":{"type":"string","description":"Purchase order reference"},"project":{"type":"string","description":"Project reference"},"accountNumber":{"type":"string","description":"Account number"}}}}},"Sharing":{"required":["reference","startDate","dataPacksCodes","assetIds","recipient","notificationEnabled","properties"],"type":"object","properties":{"reference":{"type":"string","description":"It can be a contract reference for instance"},"startDate":{"description":"Date from which the sharing of data should start serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ).","type":"string","format":"date-time"},"endDate":{"description":"Date when the sharing of data should stop serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). Equipment data will be shared as long as it is empty, so you can set it to `null` if the end date is unsure","type":"string","format":"date-time"},"status":{"description":"Current status of the sharing:\n- pending: The beneficiary user has not yet created an organization in Hiboo\n- planned: The sharing will be active (\"in progress\" status) as soon as the start date is reached\n- in_progress: The sharing is in progress and the beneficiary users have access to the assets data stream\n- stopped: The sharing has been stopped before the initially scheduled end date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history\n- completed: The sharing has ended on the scheduled date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history\n","type":"string","enum":["pending","planned","in_progress","stopped","completed"]},"dataPacksCodes":{"description":"List of data packs shared","type":"array","minItems":0,"items":{"type":"string","enum":["essential","vehicle_conditions","energy_and_fuel","activity","others","usage_hours","fault_codes"]}},"assetIds":{"description":"All the equipment that you wish to share, use Hiboo's ids","type":"array","minItems":1,"items":{"type":"number","format":"int32"}},"recipient":{"description":"Recipient's email address","type":"string","format":"email"},"notificationEnabled":{"description":"Defines if the notification is enabled on the sharing creation/start actions","type":"boolean"},"properties":{"type":"object","description":"Additional properties of the sharing","properties":{"customer":{"type":"string","description":"Customer name"},"site":{"type":"string","description":"Site name"},"contract":{"type":"string","description":"Contract reference"},"purchaseOrder":{"type":"string","description":"Purchase order reference"},"project":{"type":"string","description":"Project reference"},"accountNumber":{"type":"string","description":"Account number"}}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/sharings":{"post":{"tags":["Hiboo Connect"],"summary":"Create a new Sharing","description":"This endpoint will allow you to create a new instance of Sharing. It can be a contract for instance.","operationId":"addSharing","requestBody":{"description":"More information about the required payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSharingBody"}}},"required":true},"responses":{"201":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sharing"}}}},"400":{"description":"Invalid input or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"409":{"description":"Unique reference is already used by another sharing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}}}}} ``` ## Get a sharing > Returns a single sharing by reference ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Hiboo Connect","description":"The following endpoints allow you to share your equipment data with other organizations, and manage the sharing process."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"Sharing":{"required":["reference","startDate","dataPacksCodes","assetIds","recipient","notificationEnabled","properties"],"type":"object","properties":{"reference":{"type":"string","description":"It can be a contract reference for instance"},"startDate":{"description":"Date from which the sharing of data should start serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ).","type":"string","format":"date-time"},"endDate":{"description":"Date when the sharing of data should stop serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). Equipment data will be shared as long as it is empty, so you can set it to `null` if the end date is unsure","type":"string","format":"date-time"},"status":{"description":"Current status of the sharing:\n- pending: The beneficiary user has not yet created an organization in Hiboo\n- planned: The sharing will be active (\"in progress\" status) as soon as the start date is reached\n- in_progress: The sharing is in progress and the beneficiary users have access to the assets data stream\n- stopped: The sharing has been stopped before the initially scheduled end date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history\n- completed: The sharing has ended on the scheduled date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history\n","type":"string","enum":["pending","planned","in_progress","stopped","completed"]},"dataPacksCodes":{"description":"List of data packs shared","type":"array","minItems":0,"items":{"type":"string","enum":["essential","vehicle_conditions","energy_and_fuel","activity","others","usage_hours","fault_codes"]}},"assetIds":{"description":"All the equipment that you wish to share, use Hiboo's ids","type":"array","minItems":1,"items":{"type":"number","format":"int32"}},"recipient":{"description":"Recipient's email address","type":"string","format":"email"},"notificationEnabled":{"description":"Defines if the notification is enabled on the sharing creation/start actions","type":"boolean"},"properties":{"type":"object","description":"Additional properties of the sharing","properties":{"customer":{"type":"string","description":"Customer name"},"site":{"type":"string","description":"Site name"},"contract":{"type":"string","description":"Contract reference"},"purchaseOrder":{"type":"string","description":"Purchase order reference"},"project":{"type":"string","description":"Project reference"},"accountNumber":{"type":"string","description":"Account number"}}}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/sharings/{reference}":{"get":{"tags":["Hiboo Connect"],"summary":"Get a sharing","description":"Returns a single sharing by reference","operationId":"getSharing","parameters":[{"name":"reference","in":"path","description":"The reference you defined when creating the sharing","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sharing"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"}}}}}} ``` ## Delete a Sharing > It totally deletes a Sharing as it never existed. This will only work if the Sharing has not started yet. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Hiboo Connect","description":"The following endpoints allow you to share your equipment data with other organizations, and manage the sharing process."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}}}},"paths":{"/v2/fleet/sharings/{reference}":{"delete":{"tags":["Hiboo Connect"],"summary":"Delete a Sharing","description":"It totally deletes a Sharing as it never existed. This will only work if the Sharing has not started yet.","operationId":"deleteSharing","parameters":[{"name":"reference","in":"path","description":"The reference you defined when creating the Sharing","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Sharing was successfully deleted"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"409":{"description":"Sharing cannot be deleted because it has already started or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` ## Update an existing sharing > Update an existing sharing by reference ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Hiboo Connect","description":"The following endpoints allow you to share your equipment data with other organizations, and manage the sharing process."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"PatchSharingBody":{"type":"object","properties":{"reference":{"type":"string","description":"It can be a contract reference for instance"},"startDate":{"description":"Date from which the sharing of data should start serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). The date must not be before one rolling year.","type":"string","format":"date-time"},"endDate":{"description":"Date when the sharing of data should stop serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). Equipment data will be shared as long as it is empty, so you can set it to `null` if the end date is unsure","type":"string","format":"date-time"},"optionalDataPackCodes":{"deprecated":true,"description":"**Deprecated.** Use `excludedDataPackCodes` instead. An optional list of data packs to share. If not specified, all data will be shared by default. If set to an empty list, only base data will be shared. Otherwise, base data and specified optional data packs will be shared. If both `optionalDataPackCodes` and `excludedDataPackCodes` are provided, `excludedDataPackCodes` will take precedence and `optionalDataPackCodes` will be ignored. idle data pack is always provided when passing optionalDataPackCodes, even if not specified, to avoid retrocompability issues. To exclude it, use excludedDataPackCodes parameter instead.","type":"array","minItems":0,"items":{"type":"string","enum":["fault_codes"]}},"excludedDataPackCodes":{"description":"An optional list of data packs to exclude from sharing. If not specified, all data will be shared by default. If set to an empty list, no data pack will be excluded. Otherwise, specified data packs will be excluded from sharing.","type":"array","minItems":0,"items":{"type":"string","enum":["fault_codes","idle"]}},"properties":{"type":"object","description":"Additional properties about the sharing","properties":{"customer":{"type":"string","description":"Customer name"},"site":{"type":"string","description":"Site name"},"contract":{"type":"string","description":"Contract reference"},"purchaseOrder":{"type":"string","description":"Purchase order reference"},"project":{"type":"string","description":"Project reference"},"accountNumber":{"type":"string","description":"Account number"}}}}},"Sharing":{"required":["reference","startDate","dataPacksCodes","assetIds","recipient","notificationEnabled","properties"],"type":"object","properties":{"reference":{"type":"string","description":"It can be a contract reference for instance"},"startDate":{"description":"Date from which the sharing of data should start serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ).","type":"string","format":"date-time"},"endDate":{"description":"Date when the sharing of data should stop serialized as an ISO8601 string with a timezone (YYYY-MM-DDTHH:mm:ssZ). Equipment data will be shared as long as it is empty, so you can set it to `null` if the end date is unsure","type":"string","format":"date-time"},"status":{"description":"Current status of the sharing:\n- pending: The beneficiary user has not yet created an organization in Hiboo\n- planned: The sharing will be active (\"in progress\" status) as soon as the start date is reached\n- in_progress: The sharing is in progress and the beneficiary users have access to the assets data stream\n- stopped: The sharing has been stopped before the initially scheduled end date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history\n- completed: The sharing has ended on the scheduled date. Beneficiary users don't have access to the assets current data stream anymore, but can still access the data history\n","type":"string","enum":["pending","planned","in_progress","stopped","completed"]},"dataPacksCodes":{"description":"List of data packs shared","type":"array","minItems":0,"items":{"type":"string","enum":["essential","vehicle_conditions","energy_and_fuel","activity","others","usage_hours","fault_codes"]}},"assetIds":{"description":"All the equipment that you wish to share, use Hiboo's ids","type":"array","minItems":1,"items":{"type":"number","format":"int32"}},"recipient":{"description":"Recipient's email address","type":"string","format":"email"},"notificationEnabled":{"description":"Defines if the notification is enabled on the sharing creation/start actions","type":"boolean"},"properties":{"type":"object","description":"Additional properties of the sharing","properties":{"customer":{"type":"string","description":"Customer name"},"site":{"type":"string","description":"Site name"},"contract":{"type":"string","description":"Contract reference"},"purchaseOrder":{"type":"string","description":"Purchase order reference"},"project":{"type":"string","description":"Project reference"},"accountNumber":{"type":"string","description":"Account number"}}}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/sharings/{reference}":{"patch":{"tags":["Hiboo Connect"],"summary":"Update an existing sharing","description":"Update an existing sharing by reference","operationId":"updateSharing","parameters":[{"name":"reference","in":"path","description":"The reference you defined when creating the Sharing","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Partial update of an existing sharing resource. Only the provided fields will be updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchSharingBody"}}},"required":true},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sharing"}}}},"400":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"409":{"description":"Sharing has already started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}}}}} ``` ## Stop the sharing > This endpoint will stop the sharing of data for the specified reference. It will not delete the sharing, but it will stop the data sharing process. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Hiboo Connect","description":"The following endpoints allow you to share your equipment data with other organizations, and manage the sharing process."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}}}},"paths":{"/v2/fleet/sharings/{reference}/in-progress":{"delete":{"tags":["Hiboo Connect"],"summary":"Stop the sharing","description":"This endpoint will stop the sharing of data for the specified reference. It will not delete the sharing, but it will stop the data sharing process.","operationId":"stopSharing","parameters":[{"name":"reference","in":"path","description":"The reference you defined when creating the Sharing","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"successful operation"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"409":{"description":"if the Sharing is not in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` # Contracts The following endpoints allow you to assign your equipments to contracts data, so that Hiboo can detect out-of-contract usages. ## List contract assignments > Returns all the contract assignments of your organization ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Contracts","description":"The following endpoints allow you to assign your equipments to contracts data, so that Hiboo can detect out-of-contract usages."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"ContractAssignment":{"required":["id","contractReference","assetId","startDate","endDate","maximumHoursPerDay","customer","workingDays","excludedDays","includedDays","excludePublicHolidays","country","dailyRate","currency"],"type":"object","properties":{"id":{"description":"Unique identifier of the contract assignment, generated by Hiboo","type":"integer","format":"int32"},"contractReference":{"description":"The reference of the contract the equipment is assigned to","type":"string"},"assetId":{"description":"Hiboo's id of the equipment assigned to the contract","type":"integer","format":"int32"},"startDate":{"description":"First day of the contract assignment (YYYY-MM-DD), asset timezone","type":"string","format":"date"},"endDate":{"description":"Last day of the contract assignment (YYYY-MM-DD), asset timezone. Must not be before the start date","type":"string","format":"date"},"maximumHoursPerDay":{"description":"Maximum number of usage hours per day allowed by the contract. `null` if the contract does not limit the daily usage","type":"number","nullable":true},"customer":{"description":"Name of the customer renting the equipment","type":"string"},"workingDays":{"description":"Days of the week on which the equipment is expected to be used under the contract","type":"array","minItems":1,"items":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]}},"excludedDays":{"description":"Specific dates (YYYY-MM-DD) excluded from the contract, even if they fall on a working day","type":"array","items":{"type":"string","format":"date"}},"includedDays":{"description":"Specific dates (YYYY-MM-DD) included in the contract, even if they do not fall on a working day","type":"array","items":{"type":"string","format":"date"}},"excludePublicHolidays":{"description":"If true, public holidays of the specified country are excluded from the contract","type":"boolean"},"country":{"description":"Country used to determine public holidays","type":"string","enum":["FR","GB"]},"dailyRate":{"description":"Daily rate charged for out-of-contract usage. `null` if not defined","type":"number","nullable":true},"currency":{"description":"Currency of the daily rate, as a 3-letter ISO 4217 code","type":"string","minLength":3,"maxLength":3}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/contracts/assignments":{"get":{"tags":["Contracts"],"summary":"List contract assignments","description":"Returns all the contract assignments of your organization","operationId":"listContractAssignments","responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ContractAssignment"}}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"}}}}}} ``` ## Create a contract assignment > Assigns an equipment to a contract for a given period. The contract assignment defines the expected usage of the equipment (working days, maximum hours per day), which is used to detect out-of-contract usage. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Contracts","description":"The following endpoints allow you to assign your equipments to contracts data, so that Hiboo can detect out-of-contract usages."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"CreateContractAssignmentBody":{"required":["contractReference","assetId","startDate","endDate","customer","workingDays","country","currency"],"type":"object","properties":{"contractReference":{"description":"The reference of the contract the equipment is assigned to","type":"string","minLength":1},"assetId":{"description":"Hiboo's id of the equipment to assign to the contract","type":"integer","format":"int32"},"startDate":{"description":"First day of the contract assignment (YYYY-MM-DD), asset timezone","type":"string","format":"date"},"endDate":{"description":"Last day of the contract assignment (YYYY-MM-DD), asset timezone. Must not be before the start date","type":"string","format":"date"},"maximumHoursPerDay":{"description":"Maximum number of usage hours per day allowed by the contract, between 0 (exclusive) and 24. Set it to `null` or omit it if the contract does not limit the daily usage","type":"number","nullable":true,"exclusiveMinimum":true,"minimum":0,"maximum":24},"customer":{"description":"Name of the customer renting the equipment","type":"string","minLength":1},"workingDays":{"description":"Days of the week on which the equipment is expected to be used under the contract","type":"array","minItems":1,"items":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]}},"excludedDays":{"description":"Specific dates (YYYY-MM-DD) to exclude from the contract, even if they fall on a working day. A date cannot be both excluded and included","type":"array","items":{"type":"string","format":"date"}},"includedDays":{"description":"Specific dates (YYYY-MM-DD) to include in the contract, even if they do not fall on a working day. A date cannot be both excluded and included","type":"array","items":{"type":"string","format":"date"}},"excludePublicHolidays":{"description":"If true, public holidays of the specified country are excluded from the contract. Defaults to false","type":"boolean"},"country":{"description":"Country used to determine public holidays","type":"string","enum":["FR","GB"]},"dailyRate":{"description":"Daily rate charged for out-of-contract usage. Must be greater than or equal to 0. Set it to `null` or omit it if not defined","type":"number","nullable":true,"minimum":0},"currency":{"description":"Currency of the daily rate, as a 3-letter ISO 4217 code","type":"string","minLength":3,"maxLength":3}}},"ContractAssignment":{"required":["id","contractReference","assetId","startDate","endDate","maximumHoursPerDay","customer","workingDays","excludedDays","includedDays","excludePublicHolidays","country","dailyRate","currency"],"type":"object","properties":{"id":{"description":"Unique identifier of the contract assignment, generated by Hiboo","type":"integer","format":"int32"},"contractReference":{"description":"The reference of the contract the equipment is assigned to","type":"string"},"assetId":{"description":"Hiboo's id of the equipment assigned to the contract","type":"integer","format":"int32"},"startDate":{"description":"First day of the contract assignment (YYYY-MM-DD), asset timezone","type":"string","format":"date"},"endDate":{"description":"Last day of the contract assignment (YYYY-MM-DD), asset timezone. Must not be before the start date","type":"string","format":"date"},"maximumHoursPerDay":{"description":"Maximum number of usage hours per day allowed by the contract. `null` if the contract does not limit the daily usage","type":"number","nullable":true},"customer":{"description":"Name of the customer renting the equipment","type":"string"},"workingDays":{"description":"Days of the week on which the equipment is expected to be used under the contract","type":"array","minItems":1,"items":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]}},"excludedDays":{"description":"Specific dates (YYYY-MM-DD) excluded from the contract, even if they fall on a working day","type":"array","items":{"type":"string","format":"date"}},"includedDays":{"description":"Specific dates (YYYY-MM-DD) included in the contract, even if they do not fall on a working day","type":"array","items":{"type":"string","format":"date"}},"excludePublicHolidays":{"description":"If true, public holidays of the specified country are excluded from the contract","type":"boolean"},"country":{"description":"Country used to determine public holidays","type":"string","enum":["FR","GB"]},"dailyRate":{"description":"Daily rate charged for out-of-contract usage. `null` if not defined","type":"number","nullable":true},"currency":{"description":"Currency of the daily rate, as a 3-letter ISO 4217 code","type":"string","minLength":3,"maxLength":3}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/contracts/assignments":{"post":{"tags":["Contracts"],"summary":"Create a contract assignment","description":"Assigns an equipment to a contract for a given period. The contract assignment defines the expected usage of the equipment (working days, maximum hours per day), which is used to detect out-of-contract usage.","operationId":"createContractAssignment","requestBody":{"description":"The contract assignment to create","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContractAssignmentBody"}}},"required":true},"responses":{"201":{"description":"Contract assignment successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractAssignment"}}}},"400":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"description":"Equipment not found in your organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}}}}} ``` ## Update a contract assignment > Replaces an existing contract assignment with the provided representation. All the fields must be provided; the contract reference and the equipment cannot be changed. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Contracts","description":"The following endpoints allow you to assign your equipments to contracts data, so that Hiboo can detect out-of-contract usages."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"EditContractAssignmentBody":{"required":["startDate","endDate","customer","workingDays","country","currency"],"type":"object","properties":{"startDate":{"description":"First day of the contract assignment (YYYY-MM-DD), asset timezone","type":"string","format":"date"},"endDate":{"description":"Last day of the contract assignment (YYYY-MM-DD), asset timezone. Must not be before the start date","type":"string","format":"date"},"maximumHoursPerDay":{"description":"Maximum number of usage hours per day allowed by the contract, between 0 (exclusive) and 24. Set it to `null` or omit it if the contract does not limit the daily usage","type":"number","nullable":true,"exclusiveMinimum":true,"minimum":0,"maximum":24},"customer":{"description":"Name of the customer renting the equipment","type":"string","minLength":1},"workingDays":{"description":"Days of the week on which the equipment is expected to be used under the contract","type":"array","minItems":1,"items":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]}},"excludedDays":{"description":"Specific dates (YYYY-MM-DD) to exclude from the contract, even if they fall on a working day. A date cannot be both excluded and included","type":"array","items":{"type":"string","format":"date"}},"includedDays":{"description":"Specific dates (YYYY-MM-DD) to include in the contract, even if they do not fall on a working day. A date cannot be both excluded and included","type":"array","items":{"type":"string","format":"date"}},"excludePublicHolidays":{"description":"If true, public holidays of the specified country are excluded from the contract. Defaults to false","type":"boolean"},"country":{"description":"Country used to determine public holidays","type":"string","enum":["FR","GB"]},"dailyRate":{"description":"Daily rate charged for out-of-contract usage. Must be greater than or equal to 0. Set it to `null` or omit it if not defined","type":"number","nullable":true,"minimum":0},"currency":{"description":"Currency of the daily rate, as a 3-letter ISO 4217 code","type":"string","minLength":3,"maxLength":3}}},"ContractAssignment":{"required":["id","contractReference","assetId","startDate","endDate","maximumHoursPerDay","customer","workingDays","excludedDays","includedDays","excludePublicHolidays","country","dailyRate","currency"],"type":"object","properties":{"id":{"description":"Unique identifier of the contract assignment, generated by Hiboo","type":"integer","format":"int32"},"contractReference":{"description":"The reference of the contract the equipment is assigned to","type":"string"},"assetId":{"description":"Hiboo's id of the equipment assigned to the contract","type":"integer","format":"int32"},"startDate":{"description":"First day of the contract assignment (YYYY-MM-DD), asset timezone","type":"string","format":"date"},"endDate":{"description":"Last day of the contract assignment (YYYY-MM-DD), asset timezone. Must not be before the start date","type":"string","format":"date"},"maximumHoursPerDay":{"description":"Maximum number of usage hours per day allowed by the contract. `null` if the contract does not limit the daily usage","type":"number","nullable":true},"customer":{"description":"Name of the customer renting the equipment","type":"string"},"workingDays":{"description":"Days of the week on which the equipment is expected to be used under the contract","type":"array","minItems":1,"items":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]}},"excludedDays":{"description":"Specific dates (YYYY-MM-DD) excluded from the contract, even if they fall on a working day","type":"array","items":{"type":"string","format":"date"}},"includedDays":{"description":"Specific dates (YYYY-MM-DD) included in the contract, even if they do not fall on a working day","type":"array","items":{"type":"string","format":"date"}},"excludePublicHolidays":{"description":"If true, public holidays of the specified country are excluded from the contract","type":"boolean"},"country":{"description":"Country used to determine public holidays","type":"string","enum":["FR","GB"]},"dailyRate":{"description":"Daily rate charged for out-of-contract usage. `null` if not defined","type":"number","nullable":true},"currency":{"description":"Currency of the daily rate, as a 3-letter ISO 4217 code","type":"string","minLength":3,"maxLength":3}}},"Error":{"required":["message","details"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"},"details":{"type":"object","description":"Additional information about the Error"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/v2/fleet/contracts/assignments/{id}":{"put":{"tags":["Contracts"],"summary":"Update a contract assignment","description":"Replaces an existing contract assignment with the provided representation. All the fields must be provided; the contract reference and the equipment cannot be changed.","operationId":"editContractAssignment","parameters":[{"name":"id","in":"path","description":"The id of the contract assignment, returned when it was created","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The new values of the contract assignment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditContractAssignmentBody"}}},"required":true},"responses":{"200":{"description":"Contract assignment successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractAssignment"}}}},"400":{"description":"Missing parameters or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"description":"Contract assignment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}}}}} ``` # Catalog The following endpoints allow you to retrieve and manage the integrations. ## Get all available data sources > This endpoint will allow you to get a list of all available data sources, including the credential fields required for each. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Catalog","description":"The following endpoints allow you to retrieve and manage the integrations."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"500Error":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}},"schemas":{"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}}},"paths":{"/catalog/dataSources":{"get":{"tags":["Catalog"],"summary":"Get all available data sources","description":"This endpoint will allow you to get a list of all available data sources, including the credential fields required for each.","operationId":"getDataSources","responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"dataSources":{"type":"array","items":{"type":"object","properties":{"code":{"description":"Unique code of the data source","type":"string"},"label":{"description":"Display name of the data source","type":"string"},"credentials":{"description":"List of credential field names required to create an integration with this data source","type":"array","items":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"500":{"$ref":"#/components/responses/500Error"}}}}}} ``` ## Get all available integrations > This endpoint will allow you to get a list of all available integrations. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Catalog","description":"The following endpoints allow you to retrieve and manage the integrations."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"GetIntegrationResponse":{"type":"object","properties":{"id":{"description":"The unique identifier of the integration","type":"number"},"name":{"description":"Name of the integration","type":"string"},"dataSourceCode":{"description":"Code of the data source","type":"string"},"status":{"description":"Status of the integration","type":"string"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"204Success":{"description":"No Content"},"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"500Error":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/catalog/integrations":{"get":{"tags":["Catalog"],"summary":"Get all available integrations","description":"This endpoint will allow you to get a list of all available integrations.","operationId":"getIntegrations","responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"integrations":{"type":"array","items":{"$ref":"#/components/schemas/GetIntegrationResponse"}}}}}}},"204":{"$ref":"#/components/responses/204Success"},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"500":{"$ref":"#/components/responses/500Error"}}}}}} ``` ## Create an integration > This endpoint will allow you to create a new integration. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Catalog","description":"The following endpoints allow you to retrieve and manage the integrations."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"CreateIntegrationBody":{"required":["integrationCredentials","integrationName","dataSourceCode"],"type":"object","properties":{"integrationCredentials":{"type":"object","description":"The credentials to connect to the data source, the content of this object will depend on the data source you want to connect to."},"integrationName":{"description":"Name of the integration","type":"string"},"dataSourceCode":{"description":"Code of the data source","type":"string"}}},"IntegrationIdResponse":{"type":"object","properties":{"integrationId":{"description":"The unique identifier of the created integration","type":"number"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"409Error":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"422Error":{"description":"Invalid input or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"500Error":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/catalog/integrations":{"post":{"tags":["Catalog"],"summary":"Create an integration","description":"This endpoint will allow you to create a new integration.","operationId":"addIntegration","requestBody":{"description":"More information about the required payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIntegrationBody"}}},"required":true},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationIdResponse"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"409":{"$ref":"#/components/responses/409Error"},"422":{"$ref":"#/components/responses/422Error"},"500":{"$ref":"#/components/responses/500Error"}}}}}} ``` ## Delete an integration > This endpoint will delete an existing integration. ⚠️ \*\*Warning\*\* This operation is irreversible. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Catalog","description":"The following endpoints allow you to retrieve and manage the integrations."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"IntegrationIdResponse":{"type":"object","properties":{"integrationId":{"description":"The unique identifier of the created integration","type":"number"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"409Error":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"500Error":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/catalog/integrations/{integrationId}":{"delete":{"tags":["Catalog"],"summary":"Delete an integration","description":"This endpoint will delete an existing integration. ⚠️ **Warning** This operation is irreversible.","operationId":"deleteIntegration","parameters":[{"name":"integrationId","in":"path","description":"The unique identifier of the integration to delete","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationIdResponse"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"409":{"$ref":"#/components/responses/409Error"},"500":{"$ref":"#/components/responses/500Error"}}}}}} ``` ## Update an integration > This endpoint will allow you to update an existing integration. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Catalog","description":"The following endpoints allow you to retrieve and manage the integrations."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"PatchIntegrationBody":{"required":["integrationName"],"type":"object","properties":{"integrationCredentials":{"type":"object","description":"The new credentials to connect to the data source, the content of this object will depend on the data source you want to connect to."},"integrationName":{"description":"The new name of the integration","type":"string"}}},"PatchIntegrationResponse":{"type":"object","properties":{"integrationId":{"description":"The unique identifier of the updated integration","type":"number"},"integrationName":{"description":"Name of the updated integration","type":"string"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"409Error":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"422Error":{"description":"Invalid input or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"500Error":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/catalog/integrations/{integrationId}":{"patch":{"tags":["Catalog"],"summary":"Update an integration","description":"This endpoint will allow you to update an existing integration.","operationId":"updateIntegration","parameters":[{"name":"integrationId","in":"path","description":"The unique identifier of the integration","required":true,"schema":{"type":"integer"}}],"requestBody":{"description":"More information about the required payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchIntegrationBody"}}},"required":true},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchIntegrationResponse"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"409":{"$ref":"#/components/responses/409Error"},"422":{"$ref":"#/components/responses/422Error"},"500":{"$ref":"#/components/responses/500Error"}}}}}} ``` ## Activate an integration > This endpoint will activate an existing integration. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Catalog","description":"The following endpoints allow you to retrieve and manage the integrations."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"IntegrationIdResponse":{"type":"object","properties":{"integrationId":{"description":"The unique identifier of the created integration","type":"number"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"500Error":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/catalog/integrations/{integrationId}/activate":{"post":{"tags":["Catalog"],"summary":"Activate an integration","description":"This endpoint will activate an existing integration.","operationId":"activateIntegration","parameters":[{"name":"integrationId","in":"path","description":"The unique identifier of the integration to activate","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationIdResponse"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"500":{"$ref":"#/components/responses/500Error"}}}}}} ``` ## Deactivate an integration > This endpoint will deactivate an existing integration. ```json {"openapi":"3.0.3","info":{"title":"Hiboo API","version":"2.0.0"},"tags":[{"name":"Catalog","description":"The following endpoints allow you to retrieve and manage the integrations."}],"servers":[{"url":"https://api.hiboo.io","description":"Production server"},{"url":"https://api-sandbox.hiboo.io","description":"Sandbox server"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"x-access-token","description":"Generate a JWT when you log in. Use it in your following requests in the header as `x-access-token: your-token-here`\n"}},"schemas":{"IntegrationIdResponse":{"type":"object","properties":{"integrationId":{"description":"The unique identifier of the created integration","type":"number"}}},"NoDetailError":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"A human readable description of the error"}}}},"responses":{"401Error":{"description":"Unable to authenticate the token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"403Error":{"description":"Insufficient permissions to access the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"404Error":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}},"500Error":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoDetailError"}}}}}},"paths":{"/catalog/integrations/{integrationId}/deactivate":{"post":{"tags":["Catalog"],"summary":"Deactivate an integration","description":"This endpoint will deactivate an existing integration.","operationId":"deactivateIntegration","parameters":[{"name":"integrationId","in":"path","description":"The unique identifier of the integration to deactivate","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationIdResponse"}}}},"401":{"$ref":"#/components/responses/401Error"},"403":{"$ref":"#/components/responses/403Error"},"404":{"$ref":"#/components/responses/404Error"},"500":{"$ref":"#/components/responses/500Error"}}}}}} ``` # Kafka API Alongside our REST API, Hiboo also exposes a **Kafka API** for customers who need equipment data delivered as a continuous, low-latency stream rather than fetched on demand. ## When to use the Kafka API The REST API is the primary way to integrate with Hiboo and covers most use cases: fleet browsing, history, snapshots, and reporting. The Kafka API complements it when you need: * **Real-time data**: events are pushed as soon as Hiboo processes them, with no polling delay. * **Push-based integrations**: a natural fit for streaming pipelines, data lakes, and event-driven architectures. * **High-throughput ingestion**: built to handle large fleets without the overhead of pagination or rate management. > Not sure which one you need? Start with the REST API. The Kafka API is an add-on for streaming use cases and requires a dedicated onboarding. ## Authentication with mTLS The Kafka API is secured with **mutual TLS (mTLS)**. Unlike the REST API, it uses no `x-access-token` header: the client proves its identity with a certificate issued by Hiboo. When your Kafka access is provisioned, Hiboo provides: * A **client certificate** (`.crt`) * A **private key** (`.key`) * The **CA certificate** used to verify the broker (`ca.crt`) * The list of **bootstrap brokers** and the **topic** you are authorized to consume > Treat the private key like any other secret: store it securely, never commit it to source control, and request a new one if you suspect it has been exposed. ## Topic & message format Each customer is provisioned with a **single dedicated topic** carrying all of their time-series data. There is no need to subscribe to multiple topics: every `dataKind` (positions, fault codes, fuel, operating hours, and so on) flows through the same stream. Each message is a JSON object. The `dataKind` field tells you which type of data you are reading. **Example — position message:** ```json { "assetId": 123456, "datetime": "2026-04-22T14:49:07.000Z", "dataKind": "position", "dataSourceCode": "ocean", "latitude": 48.85837, "longitude": 2.294481, "postalAddress": "5 Av. Anatole France, 75007 Paris, France", "timezone": "Europe/Paris", "altitude": null, "speed": 26, "heading": null, "precision": null, "origin": null } ``` **Example — battery voltage message:** ```json { "assetId": 100, "datetime": "2024-09-14T13:08:35.000Z", "dataKind": "battery_voltage", "dataSourceCode": "volvotrucks_connect", "volts": 12.5 } ``` **Example — fault codes message:** ```json { "assetId": 100, "datetime": "2024-09-14T13:08:35.000Z", "dataKind": "fault_codes", "dataSourceCode": "volvotrucks_connect", "level": 2, "label": "D1DIG.1", "description": "GPMECU - General Purpose Machine Electronic Control Unit 1", "extraInfo": "{\"more\": "\data\"}" } ``` **Example — sensor boolean message:** ```json { "assetId": 100, "datetime": "2024-09-14T13:08:35.000Z", "dataKind": "sensor_boolean", "dataSourceCode": "samsara", "type": "checkEngineLights.stopIsOn", "status": false } ``` **Example — cumulative distance message:** ```json { "assetId": 100, "datetime": "2024-09-14T13:08:35.000Z", "dataKind": "cumulative_distance", "dataSourceCode": "volvotrucks_connect", "kilometers": 80853.3 } ``` **Example — cumulative usage hours message:** ```json { "assetId": 100, "datetime": "2024-09-14T13:08:35.000Z", "dataKind": "cumulative_usage_hours", "dataSourceCode": "volvotrucks_connect", "hours": 1802.4 } ``` **Example — engine condition message:** ```json { "assetId": 100, "datetime": "2024-09-14T13:08:35.000Z", "dataKind": "engine_condition", "dataSourceCode": "volvotrucks_connect", "running": "on", "engineNumber": "HC17007" } ``` **Example — sensor temperature message:** ```json { "assetId": 100, "datetime": "2024-09-14T13:08:35.000Z", "dataKind": "temperature", "dataSourceCode": "samsara", "type": "front - ambientTemperature", "celsius": 21.96, } ``` Key fields to know: * **`assetId`**: the Hiboo equipment identifier, matching the `id` returned by the REST fleet endpoints. * **`datetime`**: the UTC timestamp of the event (ISO 8601). Daily data kinds use **`date`** instead. * **`dataKind`**: the type of data carried by the message. Use it to route each message to the right handler on your side. * **`dataSourceCode`**: the source provider of the message. ## Getting access The Kafka API is not self-service. To request access: 1. Contact us at [support@hiboo.io](mailto:support@hiboo.io?Subject=\[Hiboo%20API]%20Kafka%20access%20request) with your use case and expected volume. 2. Our team provisions your certificates and shares the broker endpoints. 3. Connect from any Kafka-compatible client (Java, Python `confluent-kafka`, and others) configured for mTLS.