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:

Fleet

get

https://api.hiboo.iohttps://api-sandbox.hiboo.io

/v2/fleet/equipments

Returns the list of all equipments and their identity. This endpoint is paginated.

Authorizations

JWT

x-access-tokenstringRequired

Generate a JWT when you log in. Use it in your following requests in the header as x-access-token: your-token-here

Query parameters

limitinteger · int32 · max: 50Optional

The numbers of items to return

Default: 20

offsetinteger · int32Optional

The number of items to skip before starting to collect the result set

Default: 0

includeCustomFieldsinteger · int32Optional

By default, customFields are not included. If set to one, the custom fields will be included in the response

Default: 0

includeDataSourcesinteger · int32Optional

By default, data sources related to the equipment are not included. If set to one, the data sources will be included in the response

Default: 0

includeGroupinteger · int32Optional

By default, equipment group information is not included. If set to one, the group information will be included in the response

Default: 0

filterByInProgressSharingintegerOptional

This parameter allows filtering the equipments based on whether the equipment is currently involved in an in-progress sharing process or not.

Example: {"value":0,"summary":"Filter by not in progress sharing"}

Responses

200

List of equipment

application/json

401

Unable to authenticate the token

application/json

get/v2/fleet/equipments

HTTPcURLJavaScriptPython

GET /v2/fleet/equipments HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Accept: */*

{
  "data": {
    "total": 1,
    "rows": [
      {
        "id": 1,
        "name": "D8000-1",
        "make": "Caterpillar",
        "model": "8000",
        "serialNumber": "YVR001988",
        "workspaces": [
          "Workspace 1"
        ],
        "customFields": [
          {
            "name": "Custom Field 1",
            "value": "Value 1"
          }
        ],
        "group": {
          "id": 10,
          "assetIds": [
            1,
            2,
            3
          ]
        }
      }
    ]
  }
}

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:

Equipment

get

https://api.hiboo.iohttps://api-sandbox.hiboo.io

/v2/fleet/equipments/{id}

Returns the identity of the requested equipment

Authorizations

JWT

x-access-tokenstringRequired

Generate a JWT when you log in. Use it in your following requests in the header as x-access-token: your-token-here

Path parameters

idinteger · int32Required

ID of the equipment

Query parameters

includeCustomFieldsinteger · int32Optional

By default, customFields are not included. If set to one, the custom fields will be included in the response

Default: 0

Responses

200

List of equipment

application/json

401

Unable to authenticate the token

application/json

get/v2/fleet/equipments/{id}

HTTPcURLJavaScriptPython

GET /v2/fleet/equipments/{id} HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Accept: */*

{
  "data": {
    "id": 1,
    "name": "D8000-1",
    "make": "Caterpillar",
    "model": "8000",
    "serialNumber": "YVR001988",
    "workspaces": [
      "Workspace 1"
    ],
    "customFields": [
      {
        "name": "Custom Field 1",
        "value": "Value 1"
      }
    ]
  }
}

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.

Update Equipment Identity

patch

https://api.hiboo.iohttps://api-sandbox.hiboo.io

/v2/fleet/equipment

Update equipment data with assetId or (serialNumber AND make)

Authorizations

JWT

x-access-tokenstringRequired

Generate a JWT when you log in. Use it in your following requests in the header as x-access-token: your-token-here

Body

application/json

assetIdnumberOptional

serialNumberstringOptional

makestringOptional

namestringOptional

categorystringOptional

The category must exist beforehand and will not be created if it does not exist

modelstringOptional

entreprisestringOptional

yearone ofOptional

numberOptional

Responses

200

Equipment has been modified

application/json

statusstringOptionalExample: OK

400

Missing parameters or invalid parameters

application/json

401

Unable to authenticate the token

application/json

500

An error occurred while processing the request

application/json

patch/v2/fleet/equipment

HTTPcURLJavaScriptPython

PATCH /v2/fleet/equipment HTTP/1.1
Host: api.hiboo.io
x-access-token: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 125

{
  "assetId": 1,
  "serialNumber": "text",
  "make": "text",
  "name": "text",
  "category": "text",
  "model": "text",
  "entreprise": "text",
  "year": 1
}

{
  "status": "OK"
}

Example: Converting to fleet numbers

{
  "assetId": 1,
  "name": "FLEET-001"
}

Example: Using location-based naming

{
  "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:

{
  "assetId": 2,
  "model": "320EL",
  "year": 2023
}

Correcting equipment categories:

{
  "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