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:
Returns the list of all equipments and their identity. This endpoint is paginated.
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
The numbers of items to return
20The number of items to skip before starting to collect the result set
0By default, customFields are not included. If set to one, the custom fields will be included in the response
0By default, data sources related to the equipment are not included. If set to one, the data sources will be included in the response
0By default, equipment group information is not included. If set to one, the group information will be included in the response
0This parameter allows filtering the equipments based on whether the equipment is currently involved in an in-progress sharing process or not.
{"value":0,"summary":"Filter by not in progress sharing"}List of equipment
Unable to authenticate the token
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",
"pin": "12345678901234567",
"vin": "1HGBH41JXMN109186",
"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:
Returns the identity of the requested equipment
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
ID of the equipment
By default, customFields are not included. If set to one, the custom fields will be included in the response
0List of equipment
Unable to authenticate the token
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",
"pin": "12345678901234567",
"vin": "1HGBH41JXMN109186",
"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 assetCustomFields data with assetId or (serialNumber AND make)
Token returned by POST /login: a JWT, valid for 10 days. Send it in the x-access-token header, as x-access-token: <token>. The Authorization: Bearer <token> header also works. When a request returns 401, call POST /login again.
AssetCustomFields has been added
OKMissing or invalid parameters. details lists each invalid field with a stable code.
Unable to authenticate the token
An error occurred while processing the request
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
Example: Using manufacturer identification
Example: Financial tracking update
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
Last updated
Was this helpful?