FleetbaseFleetbase
Start Free Trial

Entities

Entities describe the individual goods, parcels, or items carried inside a payload. Use entities to capture dimensions, weight, declared value, tracking metadata, and customer ownership for shipment contents.

The Entity object

An entity represents an item, parcel, package, or other physical unit attached to a payload. It can include dimensions, weight, pricing, destination, customer, tracking, and metadata.
Attributes
idstringoptional

Public entity identifier.

internal_idstringoptional

Optional internal identifier for the entity.

namestringoptional

Display name for the entity.

typestringoptional

Entity type.

payloadstringoptional

Public ID of the payload attached to the entity.

destinationstringoptional

Public ID of the destination place.

customerobjectoptional

Customer contact or vendor associated with the entity.

supplierobjectoptional

Supplier associated with the entity, when loaded.

tracking_numberobjectoptional

Tracking number resource generated for the entity.

descriptionstringoptional

Human-readable entity description.

photo_urlstringoptional

Photo URL associated with the entity.

lengthnumberoptional

Entity length.

widthnumberoptional

Entity width.

heightnumberoptional

Entity height.

dimensions_unitstringoptional

Unit for length, width, and height.

weightnumberoptional

Entity weight.

weight_unitstringoptional

Unit for weight.

declared_valuecurrencyoptional

Declared value of the entity.

pricecurrencyoptional

Price of the entity.

sale_pricecurrencyoptional

Sale price of the entity.

skustringoptional

Stock keeping unit for the entity.

currencycurrencyoptional

Three-letter currency code for monetary fields.

metaobjectoptional

Additional entity metadata.

updated_attimestampoptional

Timestamp when the entity was last updated.

created_attimestampoptional

Timestamp when the entity was created.

The Entity object
{
  "id": "entity_4Mnp8Qx2Vz",
  "internal_id": "ENTITY001",
  "name": "Sample Entity",
  "type": "parcel",
  "payload": "payload_x9Z2Lm8QpA",
  "destination": "place_9Z8y7X6w5V",
  "customer": null,
  "tracking_number": {
    "id": "tracking_3Nf8Qw2YxM",
    "tracking_number": "FB-ENTITY-1001"
  },
  "description": "Sample description",
  "photo_url": null,
  "length": 10,
  "width": 5,
  "height": 8,
  "dimensions_unit": "mm",
  "weight": 2.5,
  "weight_unit": "kg",
  "declared_value": 1500,
  "price": 1200,
  "sale_price": 900,
  "sku": "SKU123",
  "currency": "USD",
  "meta": {},
  "updated_at": "2026-05-07T08:30:00.000000Z",
  "created_at": "2026-05-07T08:30:00.000000Z"
}
POST/v1/entities

Create an Entity

Creates an entity such as a parcel, package, or item. Attach it to a payload and optionally set a destination or waypoint within that payload route.

Body parameters
namestringrequired

Display name for the entity.

typestringrequired

Entity type, such as parcel, package, or another application-defined type.

internal_idstringoptional

Optional internal identifier for the entity.

descriptionstringoptional

Human-readable entity description.

payloadstringoptional

Payload ID to attach the entity to. Required when destination or waypoint is supplied.

destinationstringoptional

Place ID within the payload route to use as the entity destination.

waypointstringoptional

Alias for destination; resolves a place within the payload route.

customerstringoptional

Contact or vendor ID to assign as the entity customer.

driverstringoptional

Driver ID to associate with the entity.

emailstringoptional

Contact email associated with the entity.

weightnumberoptional

Entity weight.

weight_unitenumoptional

Unit for weight. Required when weight is supplied. One of g, oz, lb, kg.

lengthnumberoptional

Entity length.

widthnumberoptional

Entity width.

heightnumberoptional

Entity height.

dimensions_unitenumoptional

Unit for length, width, and height. Required when dimensions are supplied. One of cm, in, ft, mm, m, yd.

declared_valuecurrencyoptional

Declared value of the entity.

pricecurrencyoptional

Price of the entity.

sale_pricecurrencyoptional

Sale price of the entity.

skustringoptional

Stock keeping unit for the entity.

currencycurrencyoptional

Three-letter currency code for monetary fields.

metaobjectoptional

Additional entity metadata.

POST/v1/entities
curl -X POST https://api.fleetbase.io/v1/entities \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "SampleEntity",
    "type": "parcel",
    "payload": "{{payload_id}}",
    "customer": "ACustomer",
    "internal_id": "ENTITY001",
    "description": "Sample description",
    "meta": {
        "warehouse_bin": "1",
        "warehouse_rack": "3",
        "warehouse_section": "4"
    },
    "weight": 2.5,
    "weight_unit": "kg",
    "length": 10,
    "width": 5,
    "height": 8,
    "dimensions_unit": "mm",
    "declared_value": 1500,
    "price": 1200,
    "sale_price": 900,
    "sku": "SKU123",
    "currency": "USD"
}'
200 OK
{}
GET/v1/entities

Query Entities

Returns entities for the current company. Use filters such as type, payload, or destination to narrow the result set.

Query parameters
limitintegeroptional

Maximum number of entities to return.

offsetintegeroptional

Number of entities to skip before returning results.

sortstringoptional

Sort expression for the entity query.

typestringoptional

Filters entities by entity type.

payloadstringoptional

Filters entities by payload ID.

destinationstringoptional

Filters entities by destination place ID.

GET/v1/entities
curl https://api.fleetbase.io/v1/entities?limit=25&offset=0&sort=created_at&type=parcel \
  -H "Authorization: Bearer flb_live_…"
GET/v1/entities/:id

Retrieve an Entity

Retrieve an Entity.

GET/v1/entities/:id
curl https://api.fleetbase.io/v1/entities/:id \
  -H "Authorization: Bearer flb_live_…" \
  -H "Accept: application/json"
200 OK
{
  "id": "<string>",
  "payload": "<string>",
  "tracking_number": "<string>",
  "customer": "<string>",
  "internal_id": "<string>",
  "name": "<string>",
  "type": "<string>",
  "description": "<string>",
  "currency": "<string>",
  "weight": "<number>",
  "weight_unit": "<string>",
  "length": "<number>",
  "width": "<number>",
  "height": "<number>",
  "dimensions_unit": "<string>",
  "declared_value": "<number>",
  "sku": "<string>",
  "price": "<number>",
  "sale_price": "<number>",
  "meta": [],
  "updated_at": "<string>",
  "created_at": "<string>"
}
PUT/v1/entities/:id

Update a Entity

Updates an entity's descriptive fields, payload assignment, destination, dimensions, weight, pricing, or metadata.

Body parameters
namestringoptional

Display name for the entity.

typestringoptional

Entity type.

internal_idstringoptional

Optional internal identifier for the entity.

descriptionstringoptional

Human-readable entity description.

payloadstringoptional

Payload ID to attach the entity to.

destinationstringoptional

Place ID within the payload route to use as the entity destination.

waypointstringoptional

Alias for destination; resolves a place within the payload route.

customerstringoptional

Contact or vendor ID to assign as the entity customer.

driverstringoptional

Driver ID to associate with the entity.

weightnumberoptional

Entity weight.

weight_unitenumoptional

Unit for weight. One of g, oz, lb, kg.

lengthnumberoptional

Entity length.

widthnumberoptional

Entity width.

heightnumberoptional

Entity height.

dimensions_unitenumoptional

Unit for length, width, and height. One of cm, in, ft, mm, m, yd.

declared_valuecurrencyoptional

Declared value of the entity.

pricecurrencyoptional

Price of the entity.

sale_pricecurrencyoptional

Sale price of the entity.

skustringoptional

Stock keeping unit for the entity.

currencycurrencyoptional

Three-letter currency code for monetary fields.

metaobjectoptional

Additional entity metadata.

PUT/v1/entities/:id
curl -X PUT https://api.fleetbase.io/v1/entities/:id \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "internal_id": "ENTITY001-1",
    "description": "New entity description",
    "destination": "",
    "sku": "SKUABC123",
    "currency": "SGD"
}'
200 OK
{}
DELETE/v1/entities/:id

Delete a Entity

Delete an Entity.

DELETE/v1/entities/:id
curl -X DELETE https://api.fleetbase.io/v1/entities/:id \
  -H "Authorization: Bearer flb_live_…" \
  -H "Accept: application/json"
200 OK
{
  "deleted": "<boolean>",
  "id": "<string>"
}
Entities | Fleetbase