{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"470d91f8-1ea4-4d28-80f6-e34e5b8aa9e1","name":"FourKites Dynamic Yard APIs","description":"The FourKites Dynamic Yard APIs allow teams and systems operating at a warehouse to interact programmatically with activity in the yard. By exposing core functionality of the Dynamic Yard platform, warehouse management and other on-site systems can seamlessly interact with yard operations to drive efficiency and automation.\n\nFor more information on the FourKites Dynamic Yard solution, please visit the [Yard Management Software Overview](https://www.fourkites.com/platform/yard-management/).\n\n# Dynamic Yard Integration Points\n\nThe typical transactional flow between Dynamic Yard and a WMS (or other system) is diagrammed below. A high-level summary of how Dynamic Yard API support integration at each process in a yard operation are listed below the diagram.\n\nDynamic Yard offers a **2-way integration** which means you are able to subscribe to specific events generated in the platform to keep a warehouse or other systems up-to-date with the latest activity from the yard.\n\n\n\n### Data Flow and APIs\n\n1. **Gate Check-In:** event-based webhook captures when trailers arrive at the facility\n \n2. **Move Request API:** enables the warehouse to create spot requests to move trailers into open dock doors\n \n3. **Move Confirmation:** event-based webhook sends status events to the warehouse informing them on the lifecycle of spot tasks\n \n4. **Trailer Update API:** enables the warehouse to update trailer status, shipment detail, and other attributes as loading / unloading takes place\n \n5. **Move Request API:** enables the warehouse to create pull requests to move trailers from dock doors once loading / unloading has been completed\n \n6. **Move Confirmation:** event-based webhook sends status events to the warehouse informing them on the lifecycle of pull tasks. The warehouse can receive a status once the spotter has hooked to the trailer, effectively clearing the door\n \n7. **Trailer Confirmation:** event-based webhook informs the warehouse of any changes in a trailer's location, status, and service attributes relating to eligibility\n \n8. **Gate Check-Out:** event-based webhook captures the check-out event, completing a trailers lifecycle at the facility\n \n\n---\n\n# Which APIs to Use?\n\nThe first step should be identifying which APIs to use when integrating with Dynamic Yard. Each API is grouped under a parent category which describes its function in automating a specific workflow between external systems and Dynamic Yard. Reading through the below sections will help identify which APIs will best maximize efficiencies based upon your organization's goals.\n\n## Manage Shipment Data\n\nThe **Manage Shipment Data** section outlines APIs that typically receive data from transportation planning systems. Specifically, this relates to appointment scheduling and planning inbound/outbound deliveries to/from the facility. It is recommended to select _either_ the **Appointments** API or the **Deliveries** API as the main method of creating delivery objects in Dynamic Yard.\n\n> _Note: if your organization plans to use either the Core Track or Appointment Manager products alongside Dynamic Yard, the_ _**Loads / Appointments**_ _integration path is recommended to create pending deliveries in Dynamic Yard. If you are unsure of your organization's FourKites platform usage, please check with your FourKites Delivery Consultant_ \n \n\n- _**Appointments**_**:** If expected deliveries at a facility will have a pre-defined and known trailer ahead of time, then it's best to create pending delivery objects using the Create Appointment API. This will supply the ability to associate one or multiple deliveries to an expected trailer along with any other attributes (seal number, seal status, trailer type, carrier, etc.).\n \n\n- _**Deliveries**_**:** Useful when attributes about a trailer, carrier, or other inputs are not known ahead of time. While it is more limited in functionality than the Appointment API, it allows for a simpler format for creating deliveries if the additional information offered with Appointments are not needed or applicable (trailer type, carrier, etc.)\n \n\n- _**Loads / Appointments:**_ If you plan on leveraging either the Core Track (real-time visibility) or Appointment Manager products from FourKites, the recommendation is to create a single \"load\" object using the [Tracking API](https://documenter.getpostman.com/view/19175603/UVXkmZyw#0e14c9b1-1bdc-4898-9501-be8ce2f1f5df) . This API will simultaneously create the following data objects in FourKites:\n - **Core Track:** Load for real-time tracking and visibility using dedicated GPS and carrier integrations\n \n - **Appointment Manager:** Appointment for scheduling at a given facility\n \n - **Dynamic Yard:** Delivery to load / unload from trailers in the yard\n \n\n## Manage Trailers\n\nThe **Manage Trailers** section is crucial in enabling efficiency of yard operations. The APIs in this section support automatically creating move requests and updating the status of trailers based upon warehouse activity.\n\n- _**Equipment / Trailers**_**:** This API supplies critical functionality around updating trailer status, load status, and associating or removing deliveries (loading / unloading). This keeps the yard up to date on the warehouse's operations and can prepare the trailer to be moved to/from dock doors efficiently.\n \n\n- _**Move Requests**_**:** The other area of automation between the warehouse and yard is with generating move requests. The Move Request API supplies functionality to create and manage moves directly from an external system (most commonly a WMS). Both Spot and Pull requests can easily be created using this API. However, moves can still be created manually in Dynamic Yard for subsets of loads if needed\n \n\n- _**Manage Doors**_**:** Dynamic Yard offers a door update API to easily mark doors as active or inactive, enabling the warehouse to directly restrict which doors can be used for move request if they need to be taken out of service\n \n\n## Manage Dock Doors\n\nThe **Manage Dock Doors** section supplies optional APIs for updating the status of dock doors in Dynamic Yard. This can help keep the warehouses status in sync with doors in Dynamic Yard.\n\n- _**Manage Doors**_**:** Dynamic Yard offers a door update API to easily mark doors as active or inactive, enabling the warehouse to directly restrict which doors can be used for move request if they need to be taken out of service\n \n\n## Manage Gate Activity\n\nThe **Manage Gate Activity** section details optional APIs which can automatically check trailers into the yard based upon an external source of data.\n\n- _**Check-In**_: If another system or automated reader is capturing the check-in process, the Gate Check-In API can be used to create the same check-in event inside Dynamic Yard. This will populate the trailer in the yard and associate it to any shipments currently ready to unload.\n \n\n- _**Check-Out**_: Similar to the check-in event, if a separate system or automated reader is capturing trailers leaving the facility, sending data to the Gate Check-Out API will easily check trailers out of the yard\n \n\n## Webhooks (Events Generated by Dynamic Yard)\n\nEach webhook is meant to sync the warehouse with activities occurring in the yard. This makes consuming them crucial to maximizing efficient interaction between systems.\n\n- _**Gate Check-In:**_ This webhook notifies any subscribing system that a trailer has arrived at the facility. Key details about the trailer, its status, and any deliveries it's hauling are present on this webhook\n \n\n- _**Gate Check-Out:**_ Once a trailer has departed the yard this webhook can notify subscribing systems to mark the trailer as departed from the system\n \n\n- _**Trailer Update Confirmation:**_ This message notifies any subscribing systems that a change has occurred on a trailer. Anything from updating an attribute, condition, status, or location of a trailer will trigger this message. This is a key component to keeping downstream systems in sync with the latest details from the yard\n \n\n- _**Move Confirmation:**_ If move requests are being integrated between the warehouse and the yard, it is crucial that this webhook is in scope. This will deliver a status update on the move as it goes through its lifecycle, letting the warehouse know whether the trailer is at the door or has been moved from the door\n \n\n---\n\n# API Usage and Specifics\n\nThe FourKites API is accessible over HTTPS, is RESTful, and speaks JSON in both directions. As the API uses JSON for both requests and responses, we will assume that requests with a payload are using properly formatted JSON, however we still recommend setting the Content-Type header to the value application/json.\n\n## Generate Client Credentials\n\nThe client_id and client_secret can be generated under the “API Access” section with administrator access to the application. Follow the below steps to generate credentials for your company tenant and environment:\n\nLog in to the Dynamic Yard platform and click on **Setup**\n\n\n\nOn the left-hand navigation bar, locate the **Developer** section and click **API Access**\n\n\n\nClick the **Generate API Client** button and your credentials will be displayed. Copy the values and store in a secure location.\n\n\n\n# Status Codes and Error Handling\n\nFourKites uses conventional HTTP response codes to indicate the success or failure of an API request.\n\n- Codes in the 2xx range indicate success\n \n- Codes in the 4xx range indicate an error due to the information provided (e.g., a required parameter was omitted, an invalid value given, etc.)\n \n- Codes in the 5xx range indicate an error with FourKites' servers (these are rare)\n \n\n| **Code** | **Status** | **Description** |\n| --- | --- | --- |\n| `200` | OK | Response to a successful REST API action. The HTTP method can be GET, POST, PUT, PATCH or DELETE. |\n| `401` | Unauthorized | If received when making a token request, then the client_id or client_secret are invalid.

If received when making an API request using a bearer token, check if the token is valid or expired. If unsure, try retrieving a new token and making the request again |\n| `400` | Bad Request | Indicates that the server could not understand the request due to invalid syntax, format or input |\n| `404` | Not Found | The URL requested does not exist |\n| `500` | Internal Server Error | There was an issue with the Dynamic Yard server. Try again later |\n\nCustomer-level errors will primarily fall under the 400 status codes. These are defined by errors caused by invalid URL parameters or request fields in the JSON body. Each error will come with an error_message key explaining the cause of the error along with steps for remediation.\n\n| **Error Field** | **Description** |\n| --- | --- |\n| `error_code` | This a custom Error Code that is returned to provide more context. This is not directly related to a HTTP Status Code as it can mean request or resource specific errors as described below |\n| `error_message` | Specific message with information on the cause of the error along with steps for remediation |\n\nA few example error messages are below:\n\n\n\n\n\n## Environments\n\nFourKites Dynamic Yard offers 2 environments for customer use: staging and production. Staging should be used when testing APIs, responses, and outbound callbacks (i.e. webhooks from FourKites Dynamic Yard). The URLs for accessing both environments are below. If you do not have an account in the staging environment, please reach out to your FourKites Customer Success Manager:\n\n- Staging: [https://dy-staging.fourkites.com](https://dy-staging.fourkites.com)\n \n- Production: [https://dy.fourkites.com](https://dy.fourkites.com)\n \n\n# Postman Collection\n\nThe easiest way to start using the FourKites Dynamic Yard APIs is by clicking the **Run in Postman** button above. [Postman](https://www.getpostman.com/) is a free tool which helps developers run and debug API requests. Every endpoint you see documented here is readily available by running our Postman collection.\n\n## Import the Postman Environment\n\nTo import the Postman collection, click on **File** and then **Import**:\n\n\n\nNext, select the option on the modal window for **File** import, and load the file supplied by FourKites ending in “.postman_environment.json”. If you do not have a Postman Environment file please reach out to your FourKites Delivery Consultant or Customer Success Manager:\n\n\n\nThe following variables come pre-loaded in the collection supplied by FourKites and remain static:\n\n| **Variable Name** | **Description** |\n| --- | --- |\n| `dynamic_yard_url` | URL host for the Dynamic Yard APIs |\n| `scac` | Demo carrier SCAC code which can be used for initial testing |\n| `site_code` | Unique site code in Dynamic Yard |\n| `client_id` | Client ID used to authenticate with the Oauth2 service. Value must be generated by an admin within the customer site |\n| `secret` | Secret used to authenticate with the Oauth2 service. Value must be generated by an admin within the customer site |\n\nAdditional variables are dynamically updated when using the collection (see below section on **Pre-Request** and **Test** scripts):\n\n| **Variable Name** | **Description** |\n| --- | --- |\n| `delivery_id` | Unique identifier for a pending inbound / outbound delivery at the site |\n| `appointment_id` | Unique identifier for an appointment associated with a delivery at the site |\n| `trailer_number` | Trailer number checking into or out of the site |\n| `tractor_number` | Tractor number checking into or out of the site |\n| `scheduled_time` | Scheduled time for a delivery to arrive at the site |\n| `check_time` | Time the trailer checked into the site |\n\n## Pre-Request and Test Scripts\n\nWhen using the collection, there are embedded **Pre-Request** and **Test** scripts which will run before and after certain requests. These are meant to automatically generate or save variables to persist across calls when operating within the Postman environment. These can be helpful when staging sample data or quickly understanding API behavior without keying in and copy/pasting values across calls. You can also overwrite the pre-loaded variables and enter your own request JSON.\n\nAPIs which use the **Pre-Request** scripts to generate data are the following:\n\n- **Create Appointment** (Generates timestamps, trailer number, and delivery ID)\n \n- **Create Delivery** (Generates timestamps and delivery ID)\n \n\n\n\nAPIs which use the **Test** scripts to save data returned on responses as variables are the following:\n\n- **Generate Oauth2 Token** (Saves the `access_token`)\n \n- **Create Spot / Pull Task** (saves the unique move request ID)\n \n\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"19175603","team":3005259,"collectionId":"470d91f8-1ea4-4d28-80f6-e34e5b8aa9e1","publishedId":"2s8YzP3R29","public":true,"publicUrl":"https://dy.fourkites-integration.com","privateUrl":"https://go.postman.co/documentation/19175603-470d91f8-1ea4-4d28-80f6-e34e5b8aa9e1","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.0","publishDate":"2026-01-09T18:10:26.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/131a3bb45b9af047d4554980d0add10ff8027c8a12272bf8908c542457f55eda","favicon":"https://fourkites-integration.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://dy.fourkites-integration.com/view/metadata/2s8YzP3R29"}