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

Fleet

get

/v2/fleet/equipments

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

Authorizations

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

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
          ]
        }
      }
    ]
  }
}

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:

Equipment

get

/v2/fleet/equipments/{id}

Returns the identity of the requested equipment

Authorizations

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}

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:

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.

Add Custom Fields to Equipment

post

/v2/fleet/equipment/assetCustomFields

add assetCustomFields data with assetId or (serialNumber AND make)

Authorizations

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

assetIdnumberOptional

serialNumberstringOptional

makestringOptional

Responses

200

AssetCustomFields has been added

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

post/v2/fleet/equipment/assetCustomFields

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

{
  "assetId": 1,
  "serialNumber": "text",
  "make": "text",
  "customFields": [
    {
      "label": "text",
      "value": "text"
    }
  ]
}

{
  "status": "OK"
}

Example: Updating contract and condition information

{
  "assetId": 123,
  "customFields": [
    {
      "label": "contractStatus",
      "value": "Rented - Long Term"
    },
    {
      "label": "condition",
      "value": "Excellent"
    },
    {
      "label": "lastServiceDate",
      "value": "2024-07-15"
    }
  ]
}

Example: Using manufacturer identification

{
  "assetId": 234,
  "customFields": [
    {
      "label": "containerStatus",
      "value": "Full"
    },
    {
      "label": "materialType",
      "value": "Construction Debris"
    },
    {
      "label": "serviceRoute",
      "value": "Downtown Zone A"
    }
  ]
}

Example: Financial tracking update

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

PreviousOrganizing Fleet with Workspaces NextAttaching Documents to Equipment

Last updated 6 months ago

Was this helpful?