Skip to main content

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.

Prerequisites

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:

  1. It loads the yard once with a small number of aggregate calls (the /yard/view endpoints), not one call per spot or per asset.
  2. It does not poll. It keeps the data it loaded and listens to real-time events instead.
  3. 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.
  4. It coalesces bursts. Events that arrive close together are grouped (about 100 ms) so one burst causes one refresh.
  5. 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​

ConceptWhat it is
Asset VisitA truck's visit to the facility: plate, DOT number, driver phone, company, visitType, optional appointmentId. Created at check-in.
Asset ContainerThe 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 EventLog 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 AreaA named group of spots, for example "Docks - Building A".
SpotA physical location. type is parking or docking.
Spot AssignmentLinks 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.
Hooked vs. unhooked

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)​

FieldValues
typeTrailer, Container, Oversized, Chassis, Reefer, Other
stateFull, Empty, Partially Loaded

Asset Visit events (eventType)​

NotArrived, Arrived, Docked, Departed, Canceled, Attached, Detached, Appointment Linked, Appointment Unlinked, RejectedByCheckin, RejectedByWarehouse

Asset Container events (eventType)​

ValueCan you create it?
Arrived, Loading, Loading Complete, Unloading, Unloading Complete, Ready for Pickup, Departed, Inoperable, MissingYes, with POST /asset-container/event
In TransitNo. 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​

FieldValues
typeparking, docking
statusopen, 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.

OperationMinimum role
All GET /yard/view/*, GET /yard/spot, GET /yard/spot-area, GET /asset-visit, all /asset-container endpointsYard Driver
GET /asset-visit/{id}/yard-events, docked-summary, arrival-containerSpectator
GET /yard/spot-assignmentSpectator
POST /yard/spot-assignment, PATCH /yard/spot-assignment/{id}/reassignYard Driver
PATCH /yard/spot-assignment/{id}, DELETE /yard/spot-assignment/{id}, PATCH /yard/spot-assignment/{id}/departAttendant
PATCH /yard/spot/{id}/close, PATCH /yard/spot/{id}/openYard Driver
Create, update and delete spots and spot areas, POST /yard/spot/generate, POST /yard/spot/delete/bulkAdmin
PATCH /asset-visit/{id}Yard Driver
POST /asset-visit, DELETE /asset-visit/{id}Operator
POST /asset-visit/link-unplanned-checkin-to-appointmentOperator
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.

EndpointUse it toKey query parameters
GET /yard/view/spot-gridDraw 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-rowsGet 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-assetsGet the asset visits and containers waiting for a spot assignment.warehouseId (required); arrivedWithinDays, limit, offset, sortField, sortOrder, statuses
GET /yard/view/missing-assetsGet standalone containers whose latest status is Missing.warehouseId (required); limit
GET /yard/view/in-transit-assetsGet containers currently being moved, with origin and destination spot.warehouseId (required); limit
GET /yard/view/inventory-countsGet counts: assets per spot area, plus missing, waiting and total.warehouseId (required)
GET /yard/view/unread-message-countsGet unread driver messages per visit.warehouseId (required)
GET /yard/view/spot-detailGet 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, lastChangedDateTime
  • spotReserves[]: reservations on the spot
  • spotAssignments[]: empty when the spot is free, otherwise one assignment containing the assetVisit and/or assetContainer, each with its latest events
  • openMoveTasks[] and openCheckTasks[]: references to yard work currently open on the spot
note

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​

EndpointDefaultNotes
waiting-assets arrivedWithinDays70 removes the lookback. Maximum is 365.
waiting-assets offset0Use limit and offset to page. meta has the totals.
list-rows includeWaitingtrue
list-rows includeSpotAssignedAt, includeCheckInFormDatafalse
spot-grid, list-rowsnot paginatedOne 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

FieldRequiredDescription
warehouseIdYesWarehouse the truck arrived at.
phoneYesDriver phone in E.164 format, for example +14155552847.
useWhatsAppYesWhether to communicate with the driver over WhatsApp.
companyId or companyHintOne of themCarrier company id, or free-text carrier name when there is no company id.
isPlannedNotrue for a visit tied to an appointment.
appointmentIdWhen isPlanned is trueThe linked appointment.
visitTypeNoSee visit types.
licensePlate, dotNumberNoTruck identification.
driverNotes, driverAppointmentIdentifier, driverLanguageTagNoDriver-provided check-in data.
hasArrivedNotrue records an Arrived event for the visit. Otherwise the visit starts as NotArrived.
assetContainerDetails[]NoContainers 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-appointment with { "appointmentId": "...", "assetVisitId": "..." }
  • POST /asset-visit/unlink-checkin-from-appointment with { "appointmentId": "...", "assetVisitId": "..." }
warning

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

FieldRequiredDescription
eventTypeYesOne of the container events you can create. In Transit is rejected.
assetContainerIdYesThe container.
assetVisitIdNoThe visit the container is attached to.
{
"eventType": "Loading",
"assetContainerId": "4ddb1e68-a237-4288-ae9b-9cd65cc7332b"
}

3. Create and update containers​

POST /asset-container

FieldRequiredDescription
warehouseIdYesWarehouse.
codeYesContainer or trailer number.
typeYesSee container types.
assetVisitIdYesThe 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.
stateNoFull, Empty or Partially Loaded.
notesNoFree-form notes.
companyIdNoOwner company.
dropAppointmentId, pickupAppointmentId, loadAppointmentId, unloadAppointmentIdNoAppointments tied to the container.

PATCH /asset-container/{id} accepts the same fields (all optional) to update a container.

4. Place and move assets​

GoalCallDetails
Assign to a spotPOST /yard/spot-assignmentBody: spotId plus assetVisitId (a truck) or assetContainerId (an unhooked container). Optional observation.
Move to another spotPATCH /yard/spot-assignment/{id}/reassignBody: spotId (required), optional reason, observation, moveContainer. See reassignment behavior.
Unassign (back to waiting)DELETE /yard/spot-assignment/{id}
Leave the spotPATCH /yard/spot-assignment/{id}/departBody: departType (required).
Unhook a containerPOST /asset-visit/{id}/detach/{assetContainerId}The container stays in the same spot.
Hook a containerPOST /asset-visit/{id}/attach/{assetContainerId}

Step-by-step examples for each of these are in Yard Operations.

5. Set up the yard​

GoalCallBody
Create an areaPOST /yard/spot-areaname, warehouseId, optional observation
Create a spotPOST /yard/spotcode, type, spotAreaId, optional observation
Create many spotsPOST /yard/spot/generatenumberOfSpots, startFromNumber, type, spotAreaId, optional leadingChar
Delete many spotsPOST /yard/spot/delete/bulkSee the API reference
Close a spotPATCH /yard/spot/{id}/closereason (required), optional observation
Reopen a spotPATCH /yard/spot/{id}/openreason (required), optional observation
Read a spot's historyGET /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:

  1. 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 (or list-rows) and waiting-assets. waiting-assets is paged and has a 7-day lookback by default, so page through it with limit and offset, and set arrivedWithinDays (0 removes the lookback) to the window you need.
  2. Acknowledge first. Return 2xx right away and process the event asynchronously.
  3. Treat events as a signal. For a Departed or Arrived event 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.
  4. 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.
  5. Never refresh in parallel. If a refresh is running when new events arrive, run exactly one more refresh after it finishes.
  6. 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:

InformationRequiredExample
EnvironmentYesProduction or staging
Organization IDYesThe orgId of your organization in that environment
EntityYesAssetVisitEvent, AssetContainerEvent, AssetVisit, AssetContainer
OperationYesCreate, Update or Delete
Target URLYesThe HTTPS endpoint that receives the notifications
Custom headers or a static tokenNoFor example an Authorization header your endpoint checks
Warehouse IDNoOnly 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 entityPayload documented in the Webhooks guide
AssetVisitYes
AssetVisitEventYes. The payload includes the visit's appointmentId.
AssetContainerYes
AssetContainerEventYes. The most useful one for the yard: it tells you when a container arrives, leaves, is loaded, becomes ready for pickup or goes missing.
SpotAssignmentMentioned in the Webhooks guide, with no payload example yet.
Spot, SpotReserve, SpotAreaNot documented yet. Ask your account manager if you need them.

Things to plan for:

  • AssetVisit and AssetContainer payloads include orgId and warehouseId, so you can filter by warehouse. The documented AssetVisitEvent payload carries assetVisitId and appointmentId, and the AssetContainerEvent payload carries assetContainerId and assetVisitId. Neither has a warehouseId. Use the visit or the container to find the warehouse.
  • A failed delivery is not retried. Reconcile with spot-grid or waiting-assets on a schedule and after any outage on your side, as described above.
  • Acknowledge with a 2xx quickly 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 AssetVisit and AssetContainer: tells you that a visit or a container was created, updated or deleted.
  • Webhook on AssetVisitEvent and AssetContainerEvent: tells you what happened. Read the eventType of the payload to know when an asset arrives, departs and so on.
You want to know whenWebhook entityeventType
A driver (truck) arrivesAssetVisitEventArrived
A driver (truck) departsAssetVisitEventDeparted (a visit also ends with Canceled)
A container arrivesAssetContainerEventArrived
A container departsAssetContainerEventDeparted

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/view endpoints, 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 warehouseId and narrow reads with join, limit and arrivedWithinDays.
  • Use POST /yard/spot/generate and POST /yard/spot/delete/bulk for 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:

  1. Check-in. POST /asset-visit with hasArrived: true (add assetContainerDetails for containers on the truck). For an unplanned arrival that later matches an appointment, POST /asset-visit/link-unplanned-checkin-to-appointment.
  2. Waiting queue. GET /yard/view/waiting-assets lists the visits and containers waiting for a spot.
  3. Placement. POST /yard/spot-assignment assigns the visit or container to a spot.
  4. Dock work. POST /asset-container/event with Loading, Loading Complete, Unloading or Unloading Complete. PATCH /asset-container/{id} to update state and notes.
  5. 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, and PATCH /yard/spot-assignment/{id}/reassign to move it.
  6. Ready and departure. POST /asset-container/event with Ready for Pickup, then PATCH /yard/spot-assignment/{id}/depart with the departType that matches what leaves.
  7. Exceptions. POST /asset-container/event with Missing or Inoperable. GET /yard/view/missing-assets lists missing containers. PATCH /yard/spot/{id}/close takes a spot out of service.
  8. Monitoring. Request webhooks for AssetVisitEvent and AssetContainerEvent, and refresh spot-grid and waiting-assets when 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.