{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"83db1a31-14e3-4ca0-97cb-a2fba034098e","name":"FourKites Customer APIs","description":"The following APIs supply the ability to create and track loads in the FourKites real-time visibility platform. These services enable organizations to programmatically create planned shipments in the platform so that they can be tracked using proprietary integrations and connections with networked carriers.\n\nAdditionally, this document provides an overview of FourKites Callbacks (webhooks) which deliver event-based messages to a subscribed URL(s). This allows a customer API to listen for the latest status and events generated within the FourKites platform, streamlining integration.\n\n# FourKites Integration Points\n\nThe FourKites platform offers 3 key modules which extend the concept of visibility to different aspects of your organization:\n\n- Real-time load visibility\n \n- Order visibility\n \n- Network visibility\n \n\n## Real-Time Load Visibility\n\nThe main integration point with FourKites load visibility is the **Create Load** **API**. This API provides the baseline interface at which a shipment object can be created in FourKites. Typically, this data is sourced from a Transportation Management System (TMS) or other similar system. FourKites uses the shipment data, specifically the origin and destination, to geocode the route and track the load. This provides a baseline for generating milestones during the route along with predictive analytics and ETAs.\n\n\n\n## Order Visibility\n\nIn order to gain visibility at the order level, FourKites offers a Purchase Order API which can create a higher-level object than a load itself. Using this API allows you to manage a list of Purchase Orders which can be associated to one or multiple loads once they become active. This supplies a better way to view the lifecycle of an order. For more information on Order Visibility, please review the [FourKites product documentation](https://support-fourkites.force.com/hc/s/article/Order-Tracking-Visibility).\n\n\n\n## Network Visibility\n\nWith the network visibility feature, there is no inbound integration required with FourKites. Rather, organizations already integrated with the FourKites platform will share data with your organization, giving you visibility into inbound vendor data. Using network visibility comes with callbacks which can be sent to your APIs, supplying FourKites generated ETAs and stop related events on shared loads. For more information on Network Visibility, please review the [FourKites product documentation](https://support-fourkites.force.com/hc/s/article/Network-Visibility-Overview).\n\n\n\n# Generate API Credentials\n\nFirst, please contact your FourKites Implementation Manager or Customer Success Manager to obtain access to the FourKites platform. Once you have access to the platform, you can follow the [FourKites Knowledge Base](https://support-fourkites.force.com/hc/s/article/FourKites-Developer-Portal) on API key management.\n\n## Authentication\n\nThe Create / Update Load API uses API key to authenticate requests. Each request requires an API key in order to authenticate. Below is an example cURL request showing the basic structure of an API call:\n\n```\ncurl --location -g --request POST 'https://api-staging.fourkites.com/api/v1/tracking' \\\n--header 'apikey: API_KEY' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{}'\n\n ```\n\n## Rate Limiting\n\nFourkites APIs have rate limits that cap the number of requests that can be successfully made. If you exceed the specified rate limit, your request will be throttled, and you will receive HTTP 429 Too Many Requests response from the API. The rate limits will be applied per apikey and the default rate limit is 60 requests per minute. Please contact your Customer Success Manager to request an increase in the rate limit.\n\nBelow are the response headers related to the rate limit, that can be used for retries. For example, in cases where there are intermittent spikes in request rate, an exponential retry can be implemented.\n\n| **Header** | **Format** | **Description** |\n| --- | --- | --- |\n| X-RateLimit-Limit-minute | Integer | Total number of requests permitted for the apikey per minute |\n| X-RateLimit-Remaining-minute | Integer | Number of API request that will be accepted in the current minute |\n\n## Status Codes\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| 400 | Bad Request | Indicates that the server could not understand the request due to invalid syntax, format or input |\n| 401 | Unauthorized | Invalid API Key |\n| 403 | Forbidden | When the authentication succeeded but authenticated user doesn't have permission to the request resource |\n| 404 | Not Found | You either do not have permission or an entity does not exist |\n| 429 | Too Many Requests | Too Many Requests – Your request rate is too high. Try again later |\n| 500 | Internal Server Error | There was an issue processing the request. Please try again later or log a support ticket with FourKites |\n| 502 | Bad Gateway | Indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server. Please try again later |\n| 504 | Gateway Timeout | Indicates that the server, while acting as a gateway or proxy, cannot get a response in time. Please try again later |\n\nView more\n\n# Error Handling\n\nEach request has specific errors that are detailed throughout the documentation. This document contains a general description of errors that could occur across all request types and a description of the common error response format. There are two errors formats which denote generic/default and custom errors which can be resource or action specific.\n\n### Default Errors\n\nDefault errors contain a `message` in the body which provides information about the nature of the error:\n\nJSON\n\n```\n{\n \"message\": \"No API key found in request\"\n}\n\n ```\n\n### Custom Errors\n\nCustom errors provide an object with different keys containing information about the error. Custom error codes and the details in the `errorDetails` field are not directly related to a HTTP Status Code as it can mean request or resource specific errors as described below\n\nJSON\n\n```\n{\n \"errorCode\": 2002,\n \"errorDetails\": [\n \"Invalid value for param: shipment.type\"\n ],\n \"errorMessage\": \"Validation Exception\",\n \"occurredAt\": \"2020-07-28T06:46:30Z\",\n \"requestId\": \"brlfhvhghpuac6sl1jrg\"\n}\n\n ```\n\nThe following table outlines different custom errors:\n\n| **Error Code** | **Error Message** | **HTTP Status Code** |\n| --- | --- | --- |\n| 2001 | Message Not Readable | 400 |\n| 2002 | Validation Exception | 400 |\n| 2003 | Method Not Supported | 405 |\n| 6666 | Duplicate Data | 409 |\n| 8886 | Resources Not Found | 404 |\n| 8887 | Access Denied | 403 |\n| 9999 | An Internal Error Has Occurred | 500 |\n\n## Error Resolution and Common Validations\n\ne most common class of errors result from payload variations and field validations. This occurs when the JSON was well-formed, but when FourKites attempted to create a load, there was a data-level validation failure. The following table supplies most examples of such validation issues.\n\nAll of the below error messages will return with a `400` HTTP response code:\n\n| **Error Message** | **Resolution** |\n| --- | --- |\n| State 'ABCD' is not valid | Provide a valid 2 character state code for US and Canada and a 3 character state code for Mexico.
Example: CA, NY, ON, BCN, CAM. |\n| Postal 'EFGH' is not a valid US postal code | Provide a valid US postal code.
Example: 87901 |\n| Postal 'EFGH' is not a valid Canada postal code | Provide a valid Canada postal code.
Example: V3J |\n| Postal 'EFGH' is not a valid Mexico postal code | Provide a valid Mexico postal code.
Example: 46958 |\n| Stops should contain at least one pickup and one delivery | Ensure that you create a load with at least one pickup and one delivery stop |\n| Stops stop Earliest Appointment Time should not be greater than Latest Appointment Time | Ensure that the stop's earliest appointment time is not greater than the latest appointment time |\n| Stops cannot have appointment time earlier than 4 days | Ensure that the stop's appointment time is not earlier than 4 days from the current time |\n| Address should contain Address line 1 or city, state and country or Latitude and Longitude | While creating a load, ensure that stop address contains at least one of the following: Address Line 1, City, State, Country, Latitude/Longitude |\n| Load information is empty | Ensure that the \"load\" object is included in your API request: \\`{ \"load\": { ... } } \\` |\n| Carrier is not specified | Specify the SCAC of the Carrier |\n| Stops stop should contain both earliest and latest want times | If you want to create a load with want time as time ranges (earliest and latest want time), ensure that you provide the values for both these fields |\n| Stops stop should contain both earliest and latest want times | If you want to create a load with want time as time ranges (earliest and latest want time), ensure that you provide the values for both these fields |\n| Stops stop Earliest Want Time should not be greater than Latest Want Time | Ensure that the stop's earliest want time is not greater than the latest want time |\n\n# Postman Collection\n\nThe easiest way to start using the FourKites 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 the **Run in Postman** button in the top right corner of this page. This will open the embedded collection in your Postman application.\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 Implementation Manager 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| `gatewayUrl` | URL host for the FourKites APIs |\n| `scac` | Demo carrier SCAC code which can be used for initial testing |\n| `apiKey` | API Key used for authentication. Please sure this key is kept private |\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| `loadNumber` | Load number for the load. A random, unique value will be automatically generated in the “Pre-Request” script when the API call is executed. If you intend on testing specific values, you can overwrite the Postman variable from the JSON body |\n| `fourKitesLoad` | FourKites unique tracking ID returned on successful synchronous load creation calls. This is saved as an environment variable automatically in the “Tests” tab so that it does not need to be copy/pasted when performing load updates |\n| `pickupEarly` | Date/time generated for the early part of the pickup window. If you intend on testing specific values, you can overwrite the Postman variable from the JSON body |\n| `pickupLate` | Date/time generated for the late part of the pickup window. If you intend on testing specific values, you can overwrite the Postman variable from the JSON body |\n| `deliverEarly` | Date/time generated for the early part of the delivery window. If you intend on testing specific values, you can overwrite the Postman variable from the JSON body |\n| `deliverLate` | Date/time generated for the late part of the delivery window. If you intend on testing specific values, you can overwrite the Postman variable from the JSON body |\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\nVariables generated in the **Pre-Request** scripts are the following:\n\n- `loadNumber` is generated from a Uuid. This can be overwritten if testing with specific values\n \n- `pickupEarly` is generated using a present date to ensure appointments are always current\n \n- `pickupLate` is generated using a present date to ensure appointments are always current\n \n- `deliverEarly` is generated using a present date to ensure appointments are always current\n \n- `deliverLate` is generated using a present date to ensure appointments are always current\n \n\n\n\nVariables saved in the **Tests** scripts from the API response are the following:\n\n- `fourKitesLoad` saved automatically after creating a load so the value does not need to be copy/pasted into the URL when performing a **Load Update** or **Delete Load** request\n \n\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"19175603","team":3005259,"collectionId":"83db1a31-14e3-4ca0-97cb-a2fba034098e","publishedId":"UVeAwUu1","public":true,"publicUrl":"https://documenter-api.postman.tech/view/19175603/UVeAwUu1","privateUrl":"https://go.postman.co/documentation/19175603-83db1a31-14e3-4ca0-97cb-a2fba034098e","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"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":"EF5B25"}}]}},"version":"8.10.1","publishDate":"2023-09-11T20:25:25.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"FourKites Demo Environment","id":"a2529648-50d8-4665-b5ae-8275cb7c4e6b","owner":"19175603","values":[{"key":"fourKitesLoad","value":"165589369","enabled":true},{"key":"loadNumber","value":"601E5D3C","enabled":true},{"key":"deliverEarly","value":"2021-04-01T16:17:40.288Z","enabled":true},{"key":"deliverLate","value":"2021-04-02T16:17:40.288Z","enabled":true},{"key":"scac","value":"cc79","enabled":true},{"key":"pickupEarly","value":"2021-03-09T15:25:00.203Z","enabled":true},{"key":"pickupLate","value":"2021-03-09T15:25:00.203Z","enabled":true},{"key":"gatewayUrl","value":"https://api-staging.fourkites.com","enabled":true},{"key":"fourKitesStopId","value":"474588408","enabled":true,"type":"default"},{"key":"start_date","value":"2022-01-14","enabled":true,"type":"default"},{"key":"endDate","value":"2022-01-19","enabled":true},{"key":"apiKey","value":"DEMO_KEY","enabled":true,"type":"default"},{"key":"pickUpEarly","value":"","enabled":true,"type":"any"},{"key":"pickUpLate","value":"","enabled":true,"type":"any"},{"key":"startDate","value":"","enabled":true,"type":"any"},{"key":"bookingUsername","value":"test_username","enabled":true,"type":"default"},{"key":"bookingPassword","value":"test_password","enabled":true,"type":"default"}],"published":true}],"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/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":""},"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"},{"label":"FourKites Demo Environment","value":"19175603-a2529648-50d8-4665-b5ae-8275cb7c4e6b"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/UVeAwUu1"}