API Integration with Yard
This guide shows how to automate the yard from your own systems by doing what the Opendock yard screen does: read the yard state, react to changes, and write the same operations a yard attendant performs. It focuses on doing this efficiently: load the state once, then follow changes with webhooks instead of polling.
This guide builds on three others. Read them first if you have not:
- Authentication to obtain the JWT used by every call below.
- Gate Operations to understand Asset Visits and check-in.
- Yard Operations for the step-by-step spot operations (assign, reassign, detach, attach, depart, close, reopen). This guide links to it instead of repeating those examples.
How the yard screen works
The yard screen is a good model for an integration because it is built to stay fast on large yards:
- It loads the yard once with a small number of aggregate calls (the
/yard/viewendpoints), not one call per spot or per asset. - It does not poll. It keeps the data it loaded and listens to real-time events instead.
- It treats an event as a signal. When an event arrives for its warehouse, it refreshes the aggregate read. It does not try to patch its local copy field by field.
- It coalesces bursts. Events that arrive close together are grouped (about 100 ms) so one burst causes one refresh.
- It does nothing while hidden. If the screen is not visible, it remembers that a refresh is pending and does it when the screen is shown again.
The rest of this guide maps each of these behaviors to the API.
Core concepts
| Concept | What it is |
|---|---|
| Asset Visit | A truck's visit to the facility: plate, DOT number, driver phone, company, visitType, optional appointmentId. Created at check-in. |
| Asset Container | The trailer or container itself: code, type, state, drop and pickup appointments. It can be hooked to a visit or unhooked (standalone). |
| Asset Visit Event / Asset Container Event | Log entries. Status is not a stored field: it is the latest event. A container is "Missing" or "In Transit" when its latest event says so. |
| Spot Area | A named group of spots, for example "Docks - Building A". |
| Spot | A physical location. type is parking or docking. |
| Spot Assignment | Links an Asset Visit or an Asset Container to a Spot. A spot has at most one assignment, and that assignment can hold a truck and an unhooked container together. See Spot Occupancy Rules. |
A hooked container lives inside its visit (assetVisit.assetContainers). An unhooked container is a standalone entity (assetVisitId is null) and is assigned to a spot on its own. A complete yard view needs both. The /yard/view endpoints below already return both, so you do not need to query visits and containers separately.
Reference values
Visit types (visitType)
LiveUnload, LiveLoad, Live, Drop, PickUp, DropHook, Unknown
Container types (type) and states (state)
| Field | Values |
|---|---|
type | Trailer, Container, Oversized, Chassis, Reefer, Other |
state | Full, Empty, Partially Loaded |
Asset Visit events (eventType)
NotArrived, Arrived, Docked, Departed, Canceled, Attached, Detached, Appointment Linked, Appointment Unlinked, RejectedByCheckin, RejectedByWarehouse
Asset Container events (eventType)
| Value | Can you create it? |
|---|---|
Arrived, Loading, Loading Complete, Unloading, Unloading Complete, Ready for Pickup, Departed, Inoperable, Missing | Yes, with POST /asset-container/event |
In Transit | No. It is set by Opendock while a move is in progress and is rejected by the create endpoint. You will still see it in reads. |
Spots
| Field | Values |
|---|---|
type | parking, docking |
status | open, closed, assigned, in_transit, reserved_manual, reserved_automated, unknown |
Departure scope (departType)
All, AssetVisit, AssetContainer
Minimum roles
Roles are ordered from most to least powerful: Owner, Admin, Operator, Attendant, Spectator, Yard Driver. An operation that requires a role is also allowed for every more powerful role. Use an integration user with the lowest role that covers what you automate.
| Operation | Minimum role |
|---|---|
All GET /yard/view/*, GET /yard/spot, GET /yard/spot-area, GET /asset-visit, all /asset-container endpoints | Yard Driver |
GET /asset-visit/{id}/yard-events, docked-summary, arrival-container | Spectator |
GET /yard/spot-assignment | Spectator |
POST /yard/spot-assignment, PATCH /yard/spot-assignment/{id}/reassign | Yard Driver |
PATCH /yard/spot-assignment/{id}, DELETE /yard/spot-assignment/{id}, PATCH /yard/spot-assignment/{id}/depart | Attendant |
PATCH /yard/spot/{id}/close, PATCH /yard/spot/{id}/open | Yard Driver |
Create, update and delete spots and spot areas, POST /yard/spot/generate, POST /yard/spot/delete/bulk | Admin |
PATCH /asset-visit/{id} | Yard Driver |
POST /asset-visit, DELETE /asset-visit/{id} | Operator |
POST /asset-visit/link-unplanned-checkin-to-appointment | Operator |
POST /asset-visit/unlink-checkin-from-appointment, POST /asset-visit/{id}/attach/{assetContainerId}, POST /asset-visit/{id}/detach/{assetContainerId} | Attendant |
Reading the yard efficiently
All /yard/view endpoints take a warehouseId and return aggregated, ready-to-render data. Yard Operations shows how to read the yard with the standard list endpoints, spot by spot and by visit and container. The /yard/view endpoints return the same picture already joined, and they are the ones the yard screen uses, so prefer them over joining several standard endpoints yourself.
| Endpoint | Use it to | Key query parameters |
|---|---|---|
GET /yard/view/spot-grid | Draw the yard map: every area with its spots, and for each spot its status, reserves, and (at most one) assignment with its container, visit, appointment and latest events. | warehouseId (required) |
GET /yard/view/list-rows | Get a flat list: one row per container or truckless visit, as named in the API reference. | warehouseId (required); includeWaiting (default true), includeSpotAssignedAt (default false), includeCheckInFormData (default false) |
GET /yard/view/waiting-assets | Get the asset visits and containers waiting for a spot assignment. | warehouseId (required); arrivedWithinDays, limit, offset, sortField, sortOrder, statuses |
GET /yard/view/missing-assets | Get standalone containers whose latest status is Missing. | warehouseId (required); limit |
GET /yard/view/in-transit-assets | Get containers currently being moved, with origin and destination spot. | warehouseId (required); limit |
GET /yard/view/inventory-counts | Get counts: assets per spot area, plus missing, waiting and total. | warehouseId (required) |
GET /yard/view/unread-message-counts | Get unread driver messages per visit. | warehouseId (required) |
GET /yard/view/spot-detail | Get everything about one spot (for a detail panel). | spotId (required); warehouseId (optional, defaults to the spot's warehouse) |
What each one returns
spot-grid returns areas[]. Each area has id, name, warehouseId and spots[]. Each spot has:
id,code,type,status,isActive,spotAreaId,createDateTime,lastChangedDateTimespotReserves[]: reservations on the spotspotAssignments[]: empty when the spot is free, otherwise one assignment containing theassetVisitand/orassetContainer, each with its latest eventsopenMoveTasks[]andopenCheckTasks[]: references to yard work currently open on the spot
openMoveTasks and openCheckTasks appear in some yard responses. Yard task management is not part of the public API. You can ignore these fields.
list-rows returns rows[]. Each row has assetContainer, assetVisit, spot, spotArea, isWaiting, assetArrivedAt, spotAssignedAt, spotReserves, appointment, pickupAppointment, dropoffAppointment and customFormData. Inside assetContainer you find code, type, state, status (the latest container event), the owner company, notes, dropAppointment, pickupAppointment and assetContainerEvents[]. Set includeCheckInFormData=true only if you need the driver's check-in answers (customFormData): it makes the response larger.
waiting-assets returns assets[] and meta. The rows are visits and containers waiting for a spot, told apart by their kind. meta has limit, offset, page, totalPages, totalRecords, sortField and sortOrder, so you can page through the queue.
Sort with sortField (createDateTime, lastChangedDateTime or appointmentStart; default createDateTime) and sortOrder (ASC or DESC; default DESC). statuses filters by container event type.
missing-assets returns assets[], each with the assetContainer, arrivedAt (latest Arrived event) and lastMissingReportAt.
in-transit-assets returns assets[], each with the assetContainer, arrivedAt, inTransitSince, originSpot, destinationSpot and assignedTo.
inventory-counts returns missing, waiting, total and byArea[]. byArea includes every active area, including areas with a count of 0.
unread-message-counts returns counts[] with assetVisitId and unreadMessagesCount. A visit with no unread messages is absent from the list: treat a missing visit as zero.
spot-detail returns the spot, its open work, and, when the assignment is an unplanned visit, arrivalContainers[], plus containersWithSamePickupAppointment[] and containersWithSameDropAppointment[].
Limits and defaults
| Endpoint | Default | Notes |
|---|---|---|
waiting-assets arrivedWithinDays | 7 | 0 removes the lookback. Maximum is 365. |
waiting-assets offset | 0 | Use limit and offset to page. meta has the totals. |
list-rows includeWaiting | true | |
list-rows includeSpotAssignedAt, includeCheckInFormData | false | |
spot-grid, list-rows | not paginated | One call returns the whole warehouse. |
Reading with the standard list endpoints
The standard list endpoints (GET /yard/spot, GET /yard/spot-area, GET /asset-visit, GET /asset-container, GET /yard/spot-assignment) support s (search), join and pagination. See Sorting and Filtering and the examples in Yard Operations. Use them for setup data (areas, spots) and for targeted lookups, for example finding the visit for one appointment:
GET /asset-visit?s={"appointmentId":"80862efd-ac23-49e0-a307-d493bd0e2de7"}&join[]=assetContainers&join[]=assetVisitEvents
Always filter by warehouseId and ask only for the relations you need with join.
Writing: what the screen does, as API calls
1. Check in a truck
POST /asset-visit
| Field | Required | Description |
|---|---|---|
warehouseId | Yes | Warehouse the truck arrived at. |
phone | Yes | Driver phone in E.164 format, for example +14155552847. |
useWhatsApp | Yes | Whether to communicate with the driver over WhatsApp. |
companyId or companyHint | One of them | Carrier company id, or free-text carrier name when there is no company id. |
isPlanned | No | true for a visit tied to an appointment. |
appointmentId | When isPlanned is true | The linked appointment. |
visitType | No | See visit types. |
licensePlate, dotNumber | No | Truck identification. |
driverNotes, driverAppointmentIdentifier, driverLanguageTag | No | Driver-provided check-in data. |
hasArrived | No | true records an Arrived event for the visit. Otherwise the visit starts as NotArrived. |
assetContainerDetails[] | No | Containers arriving with the truck. |
{
"warehouseId": "746a7b37-9592-45db-8a58-656c7727603d",
"phone": "+14155552847",
"useWhatsApp": false,
"companyHint": "ACME Trucking",
"visitType": "DropHook",
"isPlanned": false,
"hasArrived": true,
"licensePlate": "7ABC123"
}
To tie an unplanned check-in to an appointment later, or to undo that link:
POST /asset-visit/link-unplanned-checkin-to-appointmentwith{ "appointmentId": "...", "assetVisitId": "..." }POST /asset-visit/unlink-checkin-from-appointmentwith{ "appointmentId": "...", "assetVisitId": "..." }
On warehouses with Gate Management enabled, creating a visit also opens the driver message thread, which can send a text message to the phone you send. Use a number you intend to message.
To update visit data: PATCH /asset-visit/{id} accepts appointmentId, companyId, companyHint, licensePlate, dotNumber and visitType.
2. Record container events
Events are how status changes. POST /asset-container/event
| Field | Required | Description |
|---|---|---|
eventType | Yes | One of the container events you can create. In Transit is rejected. |
assetContainerId | Yes | The container. |
assetVisitId | No | The visit the container is attached to. |
{
"eventType": "Loading",
"assetContainerId": "4ddb1e68-a237-4288-ae9b-9cd65cc7332b"
}
3. Create and update containers
POST /asset-container
| Field | Required | Description |
|---|---|---|
warehouseId | Yes | Warehouse. |
code | Yes | Container or trailer number. |
type | Yes | See container types. |
assetVisitId | Yes | The visit the container belongs to. The API reference requires it. To bring in a container together with its truck, send assetContainerDetails on POST /asset-visit instead. |
state | No | Full, Empty or Partially Loaded. |
notes | No | Free-form notes. |
companyId | No | Owner company. |
dropAppointmentId, pickupAppointmentId, loadAppointmentId, unloadAppointmentId | No | Appointments tied to the container. |
PATCH /asset-container/{id} accepts the same fields (all optional) to update a container.
4. Place and move assets
| Goal | Call | Details |
|---|---|---|
| Assign to a spot | POST /yard/spot-assignment | Body: spotId plus assetVisitId (a truck) or assetContainerId (an unhooked container). Optional observation. |
| Move to another spot | PATCH /yard/spot-assignment/{id}/reassign | Body: spotId (required), optional reason, observation, moveContainer. See reassignment behavior. |
| Unassign (back to waiting) | DELETE /yard/spot-assignment/{id} | |
| Leave the spot | PATCH /yard/spot-assignment/{id}/depart | Body: departType (required). |
| Unhook a container | POST /asset-visit/{id}/detach/{assetContainerId} | The container stays in the same spot. |
| Hook a container | POST /asset-visit/{id}/attach/{assetContainerId} |
Step-by-step examples for each of these are in Yard Operations.
5. Set up the yard
| Goal | Call | Body |
|---|---|---|
| Create an area | POST /yard/spot-area | name, warehouseId, optional observation |
| Create a spot | POST /yard/spot | code, type, spotAreaId, optional observation |
| Create many spots | POST /yard/spot/generate | numberOfSpots, startFromNumber, type, spotAreaId, optional leadingChar |
| Delete many spots | POST /yard/spot/delete/bulk | See the API reference |
| Close a spot | PATCH /yard/spot/{id}/close | reason (required), optional observation |
| Reopen a spot | PATCH /yard/spot/{id}/open | reason (required), optional observation |
| Read a spot's history | GET /yard/spot/{id}/events |
POST /yard/spot/generate is the efficient way to create a block of spots: for example numberOfSpots: 20, startFromNumber: 1, leadingChar: "D" creates D1 to D20 in one call.
Staying in sync
Use webhooks to follow the yard. Opendock sends an HTTP request to an endpoint on your side whenever an entity changes, so you do not need to call the API on a timer or keep a connection open. This is the only change-notification mechanism this guide recommends.
Webhooks are an experimental feature, and they are registered by the Opendock team through your account manager. There is no self-service registration in the API. The Webhooks guide has the registration process, the payload structure and the delivery rules.
Processing webhooks the way the yard screen does
The yard screen loads once and reacts to changes. Do the same:
- Start receiving, then load once. Have your endpoint ready to accept webhooks first, so no event is missed while you load. Then call
spot-grid(orlist-rows) andwaiting-assets.waiting-assetsis paged and has a 7-day lookback by default, so page through it withlimitandoffset, and setarrivedWithinDays(0removes the lookback) to the window you need. - Acknowledge first. Return
2xxright away and process the event asynchronously. - Treat events as a signal. For a
DepartedorArrivedevent the payload already tells you what happened. For anything that needs more context, schedule a refresh of the aggregate read instead of rebuilding state from the payload. - Coalesce bursts. Group events that arrive close together and run one refresh. The yard screen groups events over about 100 ms. For a server integration, a window of 0.5 to 2 seconds is a reasonable starting point.
- Never refresh in parallel. If a refresh is running when new events arrive, run exactly one more refresh after it finishes.
- Reconcile on a schedule. A failed delivery is not retried, so also refresh the aggregate reads at startup, after any outage on your side, and at a low frequency. Every 15 to 30 minutes is a reasonable starting point.
const COALESCE_MS = 1000;
const RECONCILE_MS = 20 * 60 * 1000;
const MAX_BACKOFF_MS = 5 * 60 * 1000;
let timer = null;
let refreshing = false;
let rerun = false;
let failures = 0;
async function refreshYard() {
if (refreshing) { rerun = true; return; }
refreshing = true;
try {
await loadSpotGrid(warehouseId); // GET /yard/view/spot-grid
await loadWaitingAssets(warehouseId); // GET /yard/view/waiting-assets, all pages
failures = 0;
} catch (error) {
failures += 1;
rerun = true; // retry, with a growing delay
console.error('Yard refresh failed', error);
} finally {
refreshing = false;
if (rerun) { rerun = false; scheduleRefresh(); }
}
}
function scheduleRefresh() {
clearTimeout(timer);
const backoff = Math.min(COALESCE_MS * 2 ** failures, MAX_BACKOFF_MS);
timer = setTimeout(refreshYard, failures > 0 ? backoff : COALESCE_MS);
}
app.post('/opendock/webhooks', (req, res) => {
// Check your static header or token here, then acknowledge.
res.sendStatus(204);
const { entity, operation, data } = req.body;
recordEvent(entity, operation, data); // queue it, do not process inline
scheduleRefresh();
});
refreshYard(); // load once at startup
setInterval(refreshYard, RECONCILE_MS); // low-frequency reconciliation
Requesting webhooks
You have to request a webhook. It does not exist until the Opendock team registers it. Contact your account manager and send:
| Information | Required | Example |
|---|---|---|
| Environment | Yes | Production or staging |
| Organization ID | Yes | The orgId of your organization in that environment |
| Entity | Yes | AssetVisitEvent, AssetContainerEvent, AssetVisit, AssetContainer |
| Operation | Yes | Create, Update or Delete |
| Target URL | Yes | The HTTPS endpoint that receives the notifications |
| Custom headers or a static token | No | For example an Authorization header your endpoint checks |
| Warehouse ID | No | Only if you want the webhook limited to one warehouse |
The full registration process is in the Webhooks guide.
Registration is per organization. Each registration covers one entity and one operation for your organization. To follow an entity fully, ask for one registration per operation. For example, to know when drivers and containers enter and leave, request AssetVisitEvent with Create and AssetContainerEvent with Create.
| Yard entity | Payload documented in the Webhooks guide |
|---|---|
AssetVisit | Yes |
AssetVisitEvent | Yes. The payload includes the visit's appointmentId. |
AssetContainer | Yes |
AssetContainerEvent | Yes. The most useful one for the yard: it tells you when a container arrives, leaves, is loaded, becomes ready for pickup or goes missing. |
SpotAssignment | Mentioned in the Webhooks guide, with no payload example yet. |
Spot, SpotReserve, SpotArea | Not documented yet. Ask your account manager if you need them. |
Things to plan for:
AssetVisitandAssetContainerpayloads includeorgIdandwarehouseId, so you can filter by warehouse. The documentedAssetVisitEventpayload carriesassetVisitIdandappointmentId, and theAssetContainerEventpayload carriesassetContainerIdandassetVisitId. Neither has awarehouseId. Use the visit or the container to find the warehouse.- A failed delivery is not retried. Reconcile with
spot-gridorwaiting-assetson a schedule and after any outage on your side, as described above. - Acknowledge with a
2xxquickly and do the work asynchronously.
How to know when an asset arrives or departs
Use webhooks. Both kinds below have to be requested, as described in Requesting webhooks.
- Webhook on
AssetVisitandAssetContainer: tells you that a visit or a container was created, updated or deleted. - Webhook on
AssetVisitEventandAssetContainerEvent: tells you what happened. Read theeventTypeof the payload to know when an asset arrives, departs and so on.
| You want to know when | Webhook entity | eventType |
|---|---|---|
| A driver (truck) arrives | AssetVisitEvent | Arrived |
| A driver (truck) departs | AssetVisitEvent | Departed (a visit also ends with Canceled) |
| A container arrives | AssetContainerEvent | Arrived |
| A container departs | AssetContainerEvent | Departed |
Request the Create operation for the event entities. Every departure creates a Departed event, so these two entities catch it however it was recorded, for example with PATCH /yard/spot-assignment/{id}/depart or POST /asset-container/event. When a visit departs, the containers attached to it get their own Departed event.
Performance checklist
- Load state with
/yard/viewendpoints, not with per-asset calls. - Fetch once, then react to webhooks. Do not poll on a short timer.
- Treat every event as a refresh signal, and coalesce bursts into one refresh.
- Run one refresh at a time.
- Re-read everything after a reconnect or an outage.
- Filter by
warehouseIdand narrow reads withjoin,limitandarrivedWithinDays. - Use
POST /yard/spot/generateandPOST /yard/spot/delete/bulkfor bulk spot changes. - Use the lowest role that covers your automation.
A typical automated routine
Putting it together, here is how an integration follows a trailer through the yard:
- Check-in.
POST /asset-visitwithhasArrived: true(addassetContainerDetailsfor containers on the truck). For an unplanned arrival that later matches an appointment,POST /asset-visit/link-unplanned-checkin-to-appointment. - Waiting queue.
GET /yard/view/waiting-assetslists the visits and containers waiting for a spot. - Placement.
POST /yard/spot-assignmentassigns the visit or container to a spot. - Dock work.
POST /asset-container/eventwithLoading,Loading Complete,UnloadingorUnloading Complete.PATCH /asset-container/{id}to updatestateandnotes. - Drop and hook.
POST /asset-visit/{id}/detach/{assetContainerId}to leave a trailer,POST /asset-visit/{id}/attach/{assetContainerId}to hook it to a truck, andPATCH /yard/spot-assignment/{id}/reassignto move it. - Ready and departure.
POST /asset-container/eventwithReady for Pickup, thenPATCH /yard/spot-assignment/{id}/departwith thedepartTypethat matches what leaves. - Exceptions.
POST /asset-container/eventwithMissingorInoperable.GET /yard/view/missing-assetslists missing containers.PATCH /yard/spot/{id}/closetakes a spot out of service. - Monitoring. Request webhooks for
AssetVisitEventandAssetContainerEvent, and refreshspot-gridandwaiting-assetswhen they arrive.
Need more help?
Start with Gate Operations for the check-in model and Yard Operations for the spot operations in detail.
Check out our Warehouses API Reference for complete documentation of every endpoint and schema.
Please reach out to our support team to get help with any questions, or join our API Slack Workspace.