API - documentation
X-Authorization-ApiKey extra header parameter with your API-key if you want to call the API on your site.
For this demo, you can use the test API-key: 123456789 to test the API services. Click on the Authorize button and set the API key.
THIS DATA IS NOT REAL, PROVIDED FOR DEMO PURPOSE ONLY!!! FOR REAL DATA PLEASE CREATE THE ACCOUNT AND ACQUIRE YOUR API KEY!
| Code | Message |
|---|---|
| 0 | No errors. |
| 1 | System error. |
| 2 | Carrier not responding. |
| 3 | Container/booking not found. |
| 4 | Carrier performing system maintenance. |
| 6 | Invalid container/booking number. |
| 7 | Carrier not suported. |
| 201 | API key is not set. |
| 202 | API key incorrect |
| 203 | API key has exceeded the limit of requests. |
| 204 | Account is restricted. |
| 205 | Method not allowed. |
| 206 | SCAC is incorrect or not suported. |
| 207 | Container number is not set or invalid. |
| 208 | API service is temporary unavailable. |
| 209 | Webhook URL is incorrect. |
Tips and Recommendations for Integrating and Using Our API
FindTEU is an event-based API, which means it can be used asynchronously. In general, there are two methods for retrieving data from the FindTEU API:
- 1. HTTP Webhook Push API
- 1.1 You send a tracking request to the API with your container number, API key, and webhook URL.
- 1.2 The API responds to confirm that it has successfully received your tracking request and, within 60 seconds, sends the available container data to your webhook.
- 1.3 Once you submit a tracking request, FindTEU automatically begins tracking the container.
- 1.4 You will receive updates automatically whenever there are changes or additional data becomes available. FindTEU sends updates related to the container you are tracking via posts to your registered webhook. Updates typically occur when containers reach milestones, but ETA updates can happen at any time. Updates will stop once the container has left the final container yard, been delivered to the consignee, or been devanned.
- 1.5 At any time, you can request a list of subscribed containers from FindTEU and remove any unwanted containers from that list.
- 2. GET/POST API
- 2.1 You send a tracking request to the API with your container number and API key.
- 2.2 Within 60 seconds, the API returns the available container data to your output.
- 2.3 To update the container data, you must send another request.
To receive JSON data on your webhook side, use the following in PHP: $json = file_get_contents("php://input");
A webhook is a method for one application to automatically send real-time data or notifications to another application when specific events occur. Unlike traditional APIs, which require one application to continuously poll another for updates, a webhook uses a push mechanism to send information only when triggered. This approach is more efficient and preferred, though it does require some setup effort. You can configure the webhook URL in your API settings, which will be used whenever you send a request with the parameter use_webhook: true. Alternatively, you can include the webhook URL in each tracking request.
HTTPS is preferred for webhooks; however, you must ensure a valid certificate is in place. Otherwise, our systems will not be able to reach your URL.
The API uses Bearer Token-style authentication, meaning you must include your API key as a token in every request.
To obtain your API key, go to your account's API settings.
The token must be included in the Authorization header for each API request, as shown below:
X-Authorization-ApiKey: YOUR_API_KEY
API calls are limited to 10 requests per 10 seconds. After submitting a POST request for a container or booking number, we strongly recommend waiting for our response before sending the next request.
Typically, we respond within 25 seconds for an initial request and within 2 seconds for repeated requests for the same container or booking number. However, if you do not receive a response within 75 seconds, this may indicate a temporary loss of connectivity with a shipping line. In such cases, we recommend resubmitting the POST request within the next hour. Once connectivity is restored, you will receive the requested data.
While detailed information about errors is available in our API documentation, here is how to proceed if you receive a response with an error code other than 0:
For error:3 (Container/Booking not found) or error:7 (Carrier not supported), there is no need to resend the request in the near future, as these issues are unlikely to resolve quickly. For error:1, error:2, or error:4, these typically indicate temporary issues that should resolve within an hour.
Important:
If you are using a webhook when submitting requests, there is no need to resend the request for errors 1, 2, or 4. We will automatically push the data to your specified webhook as soon as it becomes available.
By default, we search for container data across all the shipping lines we support. However, if your system already knows which shipping line is carrying a specific container, we strongly recommend specifying the SCAC code when making a POST request. Doing so will significantly reduce response time and minimize the likelihood of errors. You can find the list of supported SCAC codes here:
https://api.findteu.com/container/scac.
In the JSON we provide, you'll find the field "container"->"completed": boolean. This field will be marked as true when the laden container has either left the final container yard at its destination, been devanned, or delivered to the consignee. This indicates that the shipment is completed. At this point, we will stop sending updates to your webhook.
If you continue to send POST requests for the same container number after completion, we may start tracking its next journey. This will count as a separate shipment and reduce your tracking limit by 1.