Skip to main content

Yard Operations

Yard Operations in Opendock enables facilities to manage the physical movement and positioning of assets within the yard. After carriers complete the check-in process through Gate Operations, the yard management system tracks assets as they move through parking areas, dock assignments, and ultimately departure — providing real-time visibility into your facility's yard activities.

Understanding Yard Management

Yard Management builds directly upon Gate Operations and tracks the continued lifecycle of Asset Visits after initial check-in. While Gate Operations handles arrival and basic information capture, Yard Operations focuses on the physical management of assets within your facility.

Prerequisites

Before working with Yard Operations, ensure you're familiar with Gate Operations, as the Asset Visit created during check-in is the foundation for all yard management activities.

Yard Areas and Spots

Every facility can have multiple areas defined within the yard, such as parking zones, dock areas, or staging locations. These areas help organize the physical space and provide structured tracking of asset positions.

Spot Areas

A Spot Area represents a logical grouping of physical locations within your facility. Examples include:

  • Dock Areas: "Docks - Building A", "Docks - Building B"
  • Parking Zones: "Trailer Parking - North", "Overflow Parking"
  • Staging Areas: "Inbound Staging", "Outbound Staging"

Each area can contain multiple individual spots where assets can be positioned.

Common API Operations

Listing Yard Areas

Retrieve all spot areas configured for a specific warehouse location.

API Endpoint:

GET /yard/spot-area?s={"warehouseId":"{warehouseId}"}

Example Request:

GET /yard/spot-area?s={"warehouseId":"746a7b37-9592-45db-8a58-656c7727603d"}

Example Response:

{
"data": [
{
"id": "ad3b423b-cb7f-47ed-a6bb-2aa49707f0bb",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"name": "Docks - Building A"
},
{
"id": "f8c2d4e1-9a3b-4f7e-8d6c-5b2a1e9f3c4d",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"name": "Docks - Building B"
},
{
"id": "c5a8b9e3-2d4f-4a1c-9e7b-6f3d2c1a8b5e",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"name": "Trailer Parking - North"
},
{
"id": "d9f3c2a1-4e5b-4c6d-8a7e-9b1f2c3d4e5a",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"name": "Inbound Staging"
}
],
"entity": "SpotArea",
"action": "read",
"count": 4,
"total": 4,
"page": 1,
"pageCount": 1
}

Understanding Spot Properties

Before retrieving spots, it's helpful to understand the key properties that define each spot:

  • code: The human-readable identifier you assigned when creating the spot. This should match the physical signage or labeling at your facility (e.g., "M1", "D45"). Drivers and yard personnel use this code to locate the spot.
  • type: The functional type of the spot, which can be either:
    • parking: A general parking or staging location for trailers and trucks
    • docking: A dock door where loading or unloading operations occur

These properties help distinguish between different areas of your yard and enable filtering based on spot functionality.

Listing Spots with Current Assignments

A natural way to view yard operations is through the lens of physical spots — understanding what's currently occupying each location in your facility. This spot-first approach provides immediate visibility into yard utilization and asset positioning.

API Endpoint:

GET /yard/spot?join[]=spotAssignments&join[]=spotAssignments.assetVisit&join[]=spotAssignments.assetContainer&s={"spotAreaId":"{spotAreaId}"}

Example Request:

GET /yard/spot?join[]=spotAssignments&join[]=spotAssignments.assetVisit&join[]=spotAssignments.assetContainer&s={"spotAreaId":"09f41a5d-90cd-43d2-bb0c-8d0a6bccc517"}

Example Response:

{
"data": [
{
"id": "2df2d58a-dbe3-4608-b9b2-1614f8f47706",
"lastChangedDateTime": "2024-10-29T17:55:08.327Z",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"code": "M1",
"type": "parking",
"spotAreaId": "09f41a5d-90cd-43d2-bb0c-8d0a6bccc517",
"observation": null,
"spotAssignments": [
{
"id": "eda06334-3751-420b-8a6c-07244d04c6ca",
"lastChangedDateTime": "2025-12-29T19:12:34.987Z",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"spotId": "2df2d58a-dbe3-4608-b9b2-1614f8f47706",
"assetVisitId": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"assetContainerId": "4ddb1e68-a237-4288-ae9b-9cd65cc7332b",
"observation": null,
"assetVisit": {
"id": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"lastChangedDateTime": "2025-10-01T18:41:42.422Z",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"appointmentId": null,
"licensePlate": null,
"dotNumber": null,
"companyId": null,
"phone": "+14155552847",
"isPlanned": false,
"companyHint": "OPENDOCK",
"driverNotes": null,
"driverAppointmentIdentifier": null,
"visitType": "DropHook",
"checkInAcknowledged": false,
"company": null,
"assetContainers": [],
"appointment": null
},
"assetContainer": {
"id": "4ddb1e68-a237-4288-ae9b-9cd65cc7332b",
"type": "Trailer",
"state": null,
"code": "2890189012",
"notes": "Manually added via Yard View",
"pickupAppointmentId": null,
"dropAppointmentId": null,
"companyId": null,
"company": null,
"pickupAppointment": null,
"dropAppointment": null,
"assetContainerEvents": [
{
"id": "62bc08d5-aafc-4919-ab56-bd5483956fa9",
"assetVisitId": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"eventType": "Arrived",
"assetVisit": {
"id": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"appointmentId": null,
"companyId": null,
"phone": "+14155552847",
"isPlanned": false,
"companyHint": "OPENDOCK",
"visitType": "DropHook",
"company": null
}
}
]
}
}
],
"spotReserves": []
}
],
"entity": "Spot",
"action": "read"
}
Spot Assignment Cardinality

Although spotAssignments is returned as an array, it will currently contain at most one element. An asset (visit or container) can have either zero spot assignments (not currently assigned to any spot) or one spot assignment (assigned to a specific spot). The array structure is maintained for potential future enhancements, but your integration can safely assume it will never have more than one active assignment at a time.

Spot Occupancy Rules

Each spot has specific limitations on what it can contain at any given time:

  • Maximum one standalone container - A spot can hold only one unhooked container (detached from any truck)
  • Maximum one truck - A spot can accommodate only one truck (asset visit), with or without containers attached
  • Truck capacity - A single truck can have up to 2 containers attached to it
  • Valid configurations - A spot can contain:
    • Only a truck (with 0-2 attached containers)
    • Only a standalone container
    • Both a truck AND a standalone container

These rules ensure proper physical space management and prevent overcrowding of yard spots.

Hooked vs. Unhooked Containers

Understanding where container data appears in the response is critical:

  • Hooked Containers: When a container is attached to a truck (hooked), it appears in spotAssignments[0].assetVisit.assetContainers[0] — the container is associated with the Asset Visit
  • Unhooked Containers: When a container is detached from a truck (unhooked), it appears directly in spotAssignments[0].assetContainer — the container is independently assigned to the spot

This distinction reflects the physical reality: hooked containers move with their trucks, while unhooked containers are independently positioned in the yard.

Listing Asset Visits with Spot Assignments

Alternatively, you can query from the asset visit perspective to understand which assets are positioned where in your yard. By joining the spot data, you can immediately see the spot code without additional API calls.

API Endpoint:

GET /asset-visit?join[]=spotAssignments||id,spotId&join[]=spotAssignments.spot||id,code,spotAreaId&s={"warehouseId":"{warehouseId}","isActive":true}

Example Request:

GET /asset-visit?join[]=spotAssignments||id,spotId&join[]=spotAssignments.spot||id,code,spotAreaId&s={"warehouseId":"746a7b37-9592-45db-8a58-656c7727603d","isActive":true}

Example Response:

{
"data": [
{
"id": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"appointmentId": null,
"licensePlate": null,
"dotNumber": null,
"companyId": null,
"phone": "+17135558219",
"isPlanned": false,
"companyHint": "OPENDOCK",
"driverNotes": null,
"driverAppointmentIdentifier": null,
"visitType": "DropHook",
"checkInAcknowledged": false,
"spotAssignments": [
{
"id": "eda06334-3751-420b-8a6c-07244d04c6ca",
"spotId": "2df2d58a-dbe3-4608-b9b2-1614f8f47706",
"spot": {
"id": "2df2d58a-dbe3-4608-b9b2-1614f8f47706",
"code": "M1"
}
}
]
}
],
"entity": "AssetVisit",
"action": "read",
"count": 1,
"total": 1,
"page": 1,
"pageCount": 1
}
note

This endpoint returns asset visits (trucks with drivers that checked in). It will not return orphan containers that have been detached and are sitting independently in your yard. See the next section for querying unhooked containers.

Listing Unhooked Asset Containers

When containers are detached from trucks during yard operations, they become independent entities assigned directly to spots. To get a complete picture of your yard, you need to query for these orphan containers separately.

API Endpoint:

GET /asset-container?join[]=spotAssignments||id,spotId&join[]=spotAssignments.spot||id,code,spotAreaId&s={"warehouseId":"{warehouseId}","isActive":true}

Example Request:

GET /asset-container?join[]=spotAssignments||id,spotId&join[]=spotAssignments.spot||id,code,spotAreaId&s={"warehouseId":"746a7b37-9592-45db-8a58-656c7727603d","isActive":true}

Example Response:

{
"data": [
{
"id": "4ddb1e68-a237-4288-ae9b-9cd65cc7332b",
"lastChangedDateTime": "2025-12-29T19:12:34.950Z",
"isActive": true,
"type": "Trailer",
"state": null,
"code": "2890189012",
"notes": "Manually added via Yard View",
"assetVisitId": null,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"pickupAppointmentId": null,
"dropAppointmentId": null,
"companyId": null,
"assetContainerEvents": [
{
"id": "62bc08d5-aafc-4919-ab56-bd5483956fa9",
"assetContainerId": "4ddb1e68-a237-4288-ae9b-9cd65cc7332b",
"assetVisitId": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"eventType": "Arrived",
"assetVisit": {
"id": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"appointmentId": null,
"companyId": null,
"phone": "+19725553641",
"isPlanned": false,
"companyHint": "OPENDOCK",
"visitType": "DropHook",
"company": null
}
}
],
"company": null,
"assetVisit": null,
"pickupAppointment": null,
"dropAppointment": null,
"spotAssignments": [
{
"id": "eda06334-3751-420b-8a6c-07244d04c6ca",
"spotId": "2df2d58a-dbe3-4608-b9b2-1614f8f47706",
"spot": {
"id": "2df2d58a-dbe3-4608-b9b2-1614f8f47706",
"code": "M1"
}
}
]
}
],
"entity": "AssetContainer",
"action": "read",
"count": 1,
"total": 1,
"page": 1,
"pageCount": 1
}
Complete Yard Visibility

To get a complete view of all assets in your yard, you need to query both:

  1. Asset Visits — trucks with drivers currently on-site
  2. Asset Containers — trailers, chassis, or containers that are unhooked and independently positioned

The assetVisitId: null field on a container indicates it's currently unhooked. The assetContainerEvents provide the history of when it was originally attached and later detached.

Retrieving Spot Details

Once you have spot IDs from asset visit assignments, you can retrieve detailed information about a specific spot, including its current assignments and the assets occupying it.

API Endpoint:

GET /yard/spot/{spotId}

Example Request:

GET /yard/spot/2df2d58a-dbe3-4608-b9b2-1614f8f47706

Example Response:

{
"data": {
"id": "2df2d58a-dbe3-4608-b9b2-1614f8f47706",
"lastChangedDateTime": "2024-10-29T17:55:08.327Z",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"code": "M1",
"type": "parking",
"spotAreaId": "09f41a5d-90cd-43d2-bb0c-8d0a6bccc517",
"observation": null,
"spotAssignments": [
{
"id": "eda06334-3751-420b-8a6c-07244d04c6ca",
"lastChangedDateTime": "2025-12-29T19:12:34.987Z",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"spotId": "2df2d58a-dbe3-4608-b9b2-1614f8f47706",
"assetVisitId": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"assetContainerId": "4ddb1e68-a237-4288-ae9b-9cd65cc7332b",
"observation": null,
"assetVisit": {
"id": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"lastChangedDateTime": "2025-10-01T18:41:42.422Z",
"isActive": true,
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"appointmentId": null,
"licensePlate": null,
"dotNumber": null,
"companyId": null,
"phone": "+14805556172",
"isPlanned": false,
"companyHint": "OPENDOCK",
"driverNotes": null,
"driverAppointmentIdentifier": null,
"visitType": "DropHook",
"checkInAcknowledged": false,
"company": null,
"assetContainers": [],
"appointment": null
},
"assetContainer": {
"id": "4ddb1e68-a237-4288-ae9b-9cd65cc7332b",
"type": "Trailer",
"state": null,
"code": "2890189012",
"notes": "Manually added via Yard View",
"pickupAppointmentId": null,
"dropAppointmentId": null,
"companyId": null,
"company": null,
"pickupAppointment": null,
"dropAppointment": null,
"assetContainerEvents": [
{
"id": "62bc08d5-aafc-4919-ab56-bd5483956fa9",
"assetVisitId": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"eventType": "Arrived",
"assetVisit": {
"id": "bfe9a8b7-f645-4454-83fe-dbbad21c04d5",
"appointmentId": null,
"companyId": null,
"phone": "+14805556172",
"isPlanned": false,
"companyHint": "OPENDOCK",
"visitType": "DropHook",
"company": null
}
}
]
}
}
],
"spotReserves": []
},
"entity": "Spot",
"action": "read"
}

This detailed endpoint is particularly useful when you need to understand exactly what's occupying a specific spot, including both the asset visit information and any unhooked containers assigned to that location.

Yard Operations

Beyond querying the current state of your yard, the API provides endpoints to actively manage asset movements and positioning. These operations enable you to orchestrate the flow of trucks and containers through your facility.

Assigning an Asset to a Spot

Assign an asset visit or container to a specific spot in your yard.

API Endpoint:

POST /yard/spot-assignment

Example Request - Assign Asset Visit:

{
"spotId": "f843cc59-8a2a-4270-ae28-b2f0a54bd308",
"assetVisitId": "e5d1e948-749f-4428-8849-88f086ea2f84"
}

Example Request - Assign Orphan Container:

{
"spotId": "61d1d4d3-1421-4d96-990c-bafcd1256285",
"assetContainerId": "f2e0927d-7732-43e4-9a52-8f1a16ea0fce"
}

Use assetVisitId when assigning a truck (with driver) to a spot, or assetContainerId when assigning an unhooked container.

Detaching a Container (Split)

Separate a container from its truck, creating an independent orphan container. This is commonly used in drop-hook operations where the truck needs to leave but the trailer remains for loading/unloading.

API Endpoint:

POST /asset-visit/{assetVisitId}/detach/{assetContainerId}

Example Request:

POST /asset-visit/e5d1e948-749f-4428-8849-88f086ea2f84/detach/fd366a73-866d-404b-a2f3-b43fc8545444

Where:

  • e5d1e948-749f-4428-8849-88f086ea2f84 is the asset visit ID
  • fd366a73-866d-404b-a2f3-b43fc8545444 is the asset container ID
note

The detached container remains in the same spot after this operation. If you need to move it to a different location, perform a subsequent spot reassignment.

Reassigning to a Different Spot

Move an asset from its current spot to a different location in the yard. The reassignment behavior depends on what's currently occupying the spot.

API Endpoint:

PATCH /yard/spot-assignment/{spotAssignmentId}/reassign

Example Request:

PATCH /yard/spot-assignment/3ae6e46a-1799-4d05-a150-b6243afd4234/reassign

Request Payload:

{
"spotId": "bece3613-b5c0-4066-9d60-4693b8b6d3fc",
"reason": "Moving to dock",
"moveContainer": false
}

Where:

  • 3ae6e46a-1799-4d05-a150-b6243afd4234 is the spot assignment ID
  • bece3613-b5c0-4066-9d60-4693b8b6d3fc is the new target spot ID
  • moveContainer is an optional boolean flag (defaults to false)

Understanding Reassignment Behavior

The reassignment logic varies based on what's in the spot:

Simple Cases (moves everything):

  • Spot contains only a truck (with or without attached container) → Moves the entire asset visit
  • Spot contains only an unhooked container → Moves the container

Complex Case (spot has BOTH detached container AND truck):

When a spot contains both a truck and a separate unhooked container:

  • Default behavior (moveContainer: false or omitted): Moves only the truck, leaving the container behind
    • You'll need a second reassignment to move the container to its own destination
  • Move container (moveContainer: true): Moves only the container, leaving the truck behind

This flexibility allows you to handle drop-hook scenarios where the truck and trailer need to be moved to different locations independently.

Example - Moving Both Assets Separately:

// First: Move the truck to a departure area
{
"spotId": "departure-area-spot-id",
"reason": "Driver departing",
"moveContainer": false
}

// Second: Move the container to a dock for loading
{
"spotId": "dock-door-spot-id",
"reason": "Moving to dock for loading",
"moveContainer": true
}

Unassigning from Spot (Move to Waiting List)

Remove an asset from its assigned spot, returning it to an unassigned state in the waiting list.

API Endpoint:

DELETE /yard/spot-assignment/{spotAssignmentId}

Example Request:

DELETE /yard/spot-assignment/55648ce5-0217-4cba-8398-028c2a08a508

Where 55648ce5-0217-4cba-8398-028c2a08a508 is the spot assignment ID.

Attaching a Container (Hook/Merge)

Connect an unhooked container to a truck, merging them back into a single asset visit. This is the reverse of the detach operation.

API Endpoint:

POST /asset-visit/{assetVisitId}/attach/{assetContainerId}

Example Request:

POST /asset-visit/9f224f83-d85d-428c-b02e-2cdf2b84415e/attach/a5e9fc2b-95d8-4ee4-ba33-07dc885bd5d8

Where:

  • 9f224f83-d85d-428c-b02e-2cdf2b84415e is the asset visit ID
  • a5e9fc2b-95d8-4ee4-ba33-07dc885bd5d8 is the asset container ID

Departing Assets

Mark an asset as departed from the facility, completing its visit lifecycle.

API Endpoint:

PATCH /yard/spot-assignment/{spotAssignmentId}/depart

Example Request:

PATCH /yard/spot-assignment/3ae6e46a-1799-4d05-a150-b6243afd4234/depart

Request Payload:

{
"departType": "All"
}

Where 3ae6e46a-1799-4d05-a150-b6243afd4234 is the spot assignment ID.

The departType parameter specifies what should depart:

  • All: Everything currently in that spot departs together
  • AssetVisit: Only the truck/driver departs (useful when leaving a container behind)
  • AssetContainer: Only the container departs (useful when a different truck picks up the container)

Closing a Spot for Maintenance

Temporarily close a spot to prevent new assignments, typically used during maintenance or when a spot is temporarily unavailable.

API Endpoint:

PATCH /yard/spot/{spotId}/close

Example Request:

PATCH /yard/spot/f843cc59-8a2a-4270-ae28-b2f0a54bd308/close

Request Payload:

{
"reason": "Dock door maintenance"
}

Where f843cc59-8a2a-4270-ae28-b2f0a54bd308 is the spot ID.

The reason field helps track why the spot was closed for operational reporting and audit purposes.

Reopening a Spot

Reopen a previously closed spot, making it available again for asset assignments.

API Endpoint:

PATCH /yard/spot/{spotId}/open

Example Request:

PATCH /yard/spot/f843cc59-8a2a-4270-ae28-b2f0a54bd308/open

Request Payload:

{
"reason": "Maintenance completed"
}

Where f843cc59-8a2a-4270-ae28-b2f0a54bd308 is the spot ID.

Once reopened, the spot becomes available for new assignments through the normal assignment workflow.

Need more help?

To understand the full lifecycle of an asset visit, start with our Gate Operations guide.

For information about configuring custom data collection during check-in, see our Creating a Load Type Form guide.

Check out our Warehouses API Reference for complete documentation of all available endpoints.

Please reach out to our support team to get help with any questions, or join our API Slack Workspace.