Integrating with Yard Assets

This guide will provide an overview of how yard assets are used in Mobiledock and will cover the process required to integrate.

Before proceeding, it is recommended that you follow the instructions in the integration setup guide.

Overview

In Mobiledock, a yard asset is a physical asset such as a container or trailer that is managed within a Mobiledock-controlled site. Assets are used to track the location, status, and operational tasks associated with these physical items throughout their lifecycle on site.

Benefits of Yard Assets

By providing Mobiledock with information about physical assets, the following benefits can be realised:

Real-time visibility of asset locations and status across the yard
Better coordination between asset positioning and booking schedules
Improved resource planning through scheduled time assignments
Enhanced load tracking and cargo management
Seamless integration with inbound and outbound booking workflows

Included on a Yard Asset

A yard asset will typically be sent to Mobiledock with the following information:

External identifier for integration with your system
Asset type classification (e.g. Container, Trailer)
Physical location assignment (space and area)
Scheduled time assignment for the asset's occupancy
Current status
Associated operational tasks with load details
Links to inbound and outbound bookings

The anatomy of a yard asset is described in additional detail later in this guide.

Requirements

To integrate with Mobiledock yard assets, the following requirements should be met:

Your organisation has API access, location functionality and yard asset functionality enabled by your account manager
You have created an API token with the appropriate permissions for Asset Management
You have a working Mobiledock configuration with defined spaces, areas, and asset types

REST Endpoint

The root endpoint of the REST API is /api/v2.

This should be appended to the base URL, specific to the environment that you are working with.

Creating a Yard Asset

Anatomy of a Yard Asset

Yard assets use the Asset object structure.

External ID

This is the unique identifier of the asset in your external system. This allows you to maintain a reference between Mobiledock and your own asset tracking system.

Type

The type classifies the asset (e.g. Container, Trailer). Asset types should be referenced by name.

Position

The position defines where the asset is physically located within the site. It consists of two components:

Property	Description
Space	The specific parking space or bay where the asset is positioned.
Area	The broader area or zone within the site.

Time Assignment

Time assignment schedules when the asset will occupy its assigned position. Both begin and end times are optional.

Property	Description
beginTime	The start time for the asset's position (UTC).
endTime	The end time for the asset's position (UTC).

Status

An optional status field that denotes the current state of the asset (e.g. Approved, In Progress, Completed). Statuses are configurable within your Mobiledock instance.

Tasks

Tasks model the operational activities associated with the asset. Multiple tasks can be defined for a single asset.

Each task contains the following information:

Property	Description
Document	Reference to an associated document (e.g. Purchase Order ID).
Direction	Either `Inbound` or `Outbound`.
Sender	The organisation sending the goods.
Receiver	The organisation receiving the goods.
Loads	Array of load specifications including type, quantity, and optional load tags.
Booking Options (Optional)	Operational requirements (e.g. "Forklift Required").

Inbound Time Range

Defines the expected arrival window for inbound operations. Both begin and end times are optional.

Outbound Time Range

Defines the scheduled departure window for outbound operations. Both begin and end times are optional.

Inbound Booking

Optional reference to an existing Mobiledock inbound booking, linked by booking ID.

Outbound Booking

Optional reference to an existing Mobiledock outbound booking, linked by booking ID.

Example Payload

In this example, we are adding a yard asset to an organisation with an ID of c10d7362-4d1f-40c3-87e3-dd46f93590cb.

{
  "externalId": "Y8800",
  "type": {
    "name": "Container"
  },
  "position": {
    "space": {
      "name": "Bay 01"
    },
    "area": {
      "name": "Warehouse"
    }
  },
  "timeAssignment": {
    "beginTime": "2025-09-01T00:00:00Z",
    "endTime": "2025-10-02T00:00:00Z"
  },
  "status": {
    "name": "Approved"
  },
  "tasks": [
    {
      "document": {
        "id": "PO-2000"
      },
      "direction": "Inbound",
      "sender": {
        "name": "Supplier A"
      },
      "receiver": {
        "name": "Tenant X"
      },
      "loads": [
        {
          "load": {
            "name": "Pallets"
          },
          "quantity": 10,
          "loadTag": "SKU-199"
        },
        {
          "load": {
            "name": "Pallets"
          },
          "quantity": 5,
          "loadTag": "SKU-094"
        }
      ]
    }
  ],
  "inboundTimeRange": {
    "beginTime": "2025-09-01T00:00:00Z",
    "endTime": "2025-09-02T00:00:00Z"
  },
  "outboundTimeRange": {
    "beginTime": "2025-09-02T00:00:00Z",
    "endTime": "2025-09-03T00:00:00Z"
  },
  "inboundBooking": {
    "id": "MDB-25-0001-123"
  }
}

In the above payload, we have modelled a container asset Y8800 with the following information:

The asset is a Container located in Bay 01 within the Warehouse area.
The asset is scheduled to occupy this position from 1st September, 2025 to 2nd September 2025 (UTC).
The asset has an Approved status.
The asset has one inbound task associated with document PO-2000, involving 10 pallets of SKU-199 and 5 pallets of SKU-094 being sent from Supplier A to Tenant X.
The inbound operation is expected between 1st September and 2nd September, 2025 (UTC).
The outbound operation is scheduled between 2nd September, 2025 and 3rd September, 2025 (UTC).
The asset is linked to inbound booking MDB-25-0001-123.

Submitting a Yard Asset

Once a valid payload has been constructed, it is ready to send to Mobiledock.

The recommended method is to use the patch / insert operation via a PATCH request. This will either update an existing asset if it already exists, or create a new one if it doesn't.

Please note that when patching a new asset, all required fields must be provided.

For example, in the Production environment if you want to add an asset to the organisation with ID 990090c9-7506-487b-9872-c4e65557ae75, the payload should be sent via an HTTP PATCH request to the following URL:

https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/assets/Y8800

Note: The external ID should be included in the URL path.

HTTP Status Codes

Status Code	Description
200	The asset has been successfully updated.
201	The asset has been successfully created.
400	There is an issue with the payload. Details can be found in the response body.

Updating a Yard Asset

Partial Updates with PATCH

If you only need to update specific fields of an existing asset, you can use the PATCH operation. This allows partial updates without replacing the entire asset record.

For example, to update only the status and position of an asset:

{
  "status": {
    "name": "Unloading"
  },
  "position": {
    "area": {
      "name": "Warehouse"
    },
    "space": {
      "name": "Bay 02"
    }
  }
}

Send this payload via an HTTP PATCH request to:

https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/assets/Y8800

HTTP Status Codes

Status Code	Description
200	The asset has been successfully updated.
400	There is an issue with the payload. Details can be found in the response body.
404	The asset does not exist.

Fetching Yard Assets

Fetching a Single Asset

To fetch a specific asset, send an HTTP GET request to the resource location:

https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/assets/Y8800

Fetching Multiple Assets

To retrieve a list of all assets for an organisation, send an HTTP GET request to:

https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/assets

HTTP Status Codes

Status Code	Description
200	The asset(s) have been successfully fetched.
404	The asset does not exist (single asset fetch only).

Deleting a Yard Asset

To remove an asset from the system, send an HTTP DELETE request to the resource location:

https://my.mobiledock.com/api/v2/organisations/990090c9-7506-487b-9872-c4e65557ae75/assets/Y8800

Note: Deleting an asset removes it from active tracking but may preserve historical records depending on your configuration.

HTTP Status Codes

Status Code	Description
200	The asset has been successfully deleted.
404	The asset does not exist.

Technical Considerations

When integrating with the Yard Assets API, keep the following in mind:

All timestamps must use ISO 8601 format with UTC timezone (e.g. 2025-09-01T00:00:00Z)
PUT operations perform full record replacement and require all mandatory fields
PATCH operations allow partial updates of specific fields only
External IDs must be unique within an organisation
Asset types, spaces, and areas must exist in your Mobiledock configuration before referencing them
Multiple tasks can be associated with a single asset to support complex operational workflows
Booking references must correspond to valid Mobiledock booking IDs

Use Cases

The Yard Assets API supports various integration scenarios:

Third-party Integration: Synchronise asset data between warehouse management systems and Mobiledock
Real-time Updates: Enable mobile applications or IoT devices to update asset status and location
Automated Scheduling: Support automated systems in managing asset time assignments and positioning
Load Tracking: Facilitate cargo management through detailed load information across multiple tasks
Booking Coordination: Link physical assets to inbound and outbound booking workflows for complete visibility

Next Steps

If after reading this guide you have any further questions, please don't hesitate to contact us at assistance@mobiledock.com.

Overview​

Benefits of Yard Assets​

Included on a Yard Asset​

Requirements​

REST Endpoint​

Creating a Yard Asset​

Anatomy of a Yard Asset​

External ID​

Type​

Position​

Time Assignment​

Status​

Tasks​

Inbound Time Range​

Outbound Time Range​

Inbound Booking​

Outbound Booking​

Example Payload​

Submitting a Yard Asset​

HTTP Status Codes​

Updating a Yard Asset​

Partial Updates with PATCH​

HTTP Status Codes​

Fetching Yard Assets​

Fetching a Single Asset​

Fetching Multiple Assets​

HTTP Status Codes​

Deleting a Yard Asset​

HTTP Status Codes​

Technical Considerations​

Use Cases​

Next Steps​

Overview

Benefits of Yard Assets

Included on a Yard Asset

Requirements

REST Endpoint

Creating a Yard Asset

Anatomy of a Yard Asset

External ID

Type

Position

Time Assignment

Status

Tasks

Inbound Time Range

Outbound Time Range

Inbound Booking

Outbound Booking

Example Payload

Submitting a Yard Asset

HTTP Status Codes

Updating a Yard Asset

Partial Updates with PATCH

HTTP Status Codes

Fetching Yard Assets

Fetching a Single Asset

Fetching Multiple Assets

HTTP Status Codes

Deleting a Yard Asset

HTTP Status Codes

Technical Considerations

Use Cases

Next Steps