# 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="<https://spec.hiboo.io/openapiv2.yml>" path="/v2/fleet/equipments" method="get" %}
<https://spec.hiboo.io/openapiv2.yml>
{% 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="<https://spec.hiboo.io/openapiv2.yml>" path="/v2/fleet/equipments/{id}" method="get" %}
<https://spec.hiboo.io/openapiv2.yml>
{% 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="<https://spec.hiboo.io/openapiv2.yml>" path="/v2/fleet/equipment" method="patch" %}
<https://spec.hiboo.io/openapiv2.yml>
{% 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hiboo.io/guides/guides/managing-your-fleet/managing-equipment-identity.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.