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.
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 trucksdocking: 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"
}
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.
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.
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
}
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
}
To get a complete view of all assets in your yard, you need to query both:
- Asset Visits — trucks with drivers currently on-site
- 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-88f086ea2f84is the asset visit IDfd366a73-866d-404b-a2f3-b43fc8545444is the asset container ID
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-b6243afd4234is the spot assignment IDbece3613-b5c0-4066-9d60-4693b8b6d3fcis the new target spot IDmoveContaineris an optional boolean flag (defaults tofalse)
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: falseor 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-2cdf2b84415eis the asset visit IDa5e9fc2b-95d8-4ee4-ba33-07dc885bd5d8is 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 togetherAssetVisit: 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.