Create a tracking request
curl --request POST \
--url https://api.terminal49.com/v2/tracking_requests \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"data": {
"attributes": {
"request_type": "bill_of_lading",
"request_number": "MEDUFR030802",
"ref_numbers": [
"PO12345",
"HBL12345",
"CUSREF1234"
],
"shipment_tags": [
"camembert"
],
"scac": "MSCU"
},
"relationships": {
"customer": {
"data": {
"id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
"type": "party"
}
}
},
"type": "tracking_request"
}
}
'import requests
url = "https://api.terminal49.com/v2/tracking_requests"
payload = { "data": {
"attributes": {
"request_type": "bill_of_lading",
"request_number": "MEDUFR030802",
"ref_numbers": ["PO12345", "HBL12345", "CUSREF1234"],
"shipment_tags": ["camembert"],
"scac": "MSCU"
},
"relationships": { "customer": { "data": {
"id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
"type": "party"
} } },
"type": "tracking_request"
} }
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
data: {
attributes: {
request_type: 'bill_of_lading',
request_number: 'MEDUFR030802',
ref_numbers: ['PO12345', 'HBL12345', 'CUSREF1234'],
shipment_tags: ['camembert'],
scac: 'MSCU'
},
relationships: {customer: {data: {id: 'f7cb530a-9e60-412c-a5bc-205a2f34ba54', type: 'party'}}},
type: 'tracking_request'
}
})
};
fetch('https://api.terminal49.com/v2/tracking_requests', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.terminal49.com/v2/tracking_requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'attributes' => [
'request_type' => 'bill_of_lading',
'request_number' => 'MEDUFR030802',
'ref_numbers' => [
'PO12345',
'HBL12345',
'CUSREF1234'
],
'shipment_tags' => [
'camembert'
],
'scac' => 'MSCU'
],
'relationships' => [
'customer' => [
'data' => [
'id' => 'f7cb530a-9e60-412c-a5bc-205a2f34ba54',
'type' => 'party'
]
]
],
'type' => 'tracking_request'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.terminal49.com/v2/tracking_requests"
payload := strings.NewReader("{\n \"data\": {\n \"attributes\": {\n \"request_type\": \"bill_of_lading\",\n \"request_number\": \"MEDUFR030802\",\n \"ref_numbers\": [\n \"PO12345\",\n \"HBL12345\",\n \"CUSREF1234\"\n ],\n \"shipment_tags\": [\n \"camembert\"\n ],\n \"scac\": \"MSCU\"\n },\n \"relationships\": {\n \"customer\": {\n \"data\": {\n \"id\": \"f7cb530a-9e60-412c-a5bc-205a2f34ba54\",\n \"type\": \"party\"\n }\n }\n },\n \"type\": \"tracking_request\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.terminal49.com/v2/tracking_requests")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"attributes\": {\n \"request_type\": \"bill_of_lading\",\n \"request_number\": \"MEDUFR030802\",\n \"ref_numbers\": [\n \"PO12345\",\n \"HBL12345\",\n \"CUSREF1234\"\n ],\n \"shipment_tags\": [\n \"camembert\"\n ],\n \"scac\": \"MSCU\"\n },\n \"relationships\": {\n \"customer\": {\n \"data\": {\n \"id\": \"f7cb530a-9e60-412c-a5bc-205a2f34ba54\",\n \"type\": \"party\"\n }\n }\n },\n \"type\": \"tracking_request\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.terminal49.com/v2/tracking_requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"attributes\": {\n \"request_type\": \"bill_of_lading\",\n \"request_number\": \"MEDUFR030802\",\n \"ref_numbers\": [\n \"PO12345\",\n \"HBL12345\",\n \"CUSREF1234\"\n ],\n \"shipment_tags\": [\n \"camembert\"\n ],\n \"scac\": \"MSCU\"\n },\n \"relationships\": {\n \"customer\": {\n \"data\": {\n \"id\": \"f7cb530a-9e60-412c-a5bc-205a2f34ba54\",\n \"type\": \"party\"\n }\n }\n },\n \"type\": \"tracking_request\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "ba4cb904-827f-4038-8e31-1e92b3356218",
"type": "tracking_request",
"attributes": {
"request_number": "MEDUFR030802",
"request_type": "bill_of_lading",
"scac": "MSCU",
"ref_numbers": [],
"created_at": "2020-04-04T16:13:35-07:00",
"updated_at": "2020-04-04T17:13:35-07:00",
"status": "pending",
"failed_reason": null
},
"relationships": {
"tracked_object": {
"data": null
},
"customer": {
"data": {
"id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
"type": "party"
}
}
},
"links": {
"self": "/v2/tracking_requests/ba4cb904-827f-4038-8e31-1e92b3356218"
}
}
}{
"errors": [
{
"status": "422",
"source": {
"pointer": "/data/attributes/scac"
},
"title": "Unprocessable Entity",
"detail": "Scac can't be blank",
"code": "blank"
},
{
"status": "422",
"source": {
"pointer": "/data/attributes/scac"
},
"title": "Unprocessable Entity",
"detail": "Scac 'XXXX' is not recognized",
"code": "blank"
},
{
"status": "422",
"source": {
"pointer": "/data/attributes/scac"
},
"title": "Unprocessable Entity",
"detail": "Scac 'UALC' is not supported. We do not currently integrate with Universal Africa Lines",
"code": "blank"
},
{
"status": "422",
"source": {
"pointer": "/data/attributes/request_number"
},
"title": "Unprocessable Entity",
"detail": "Request number can't be blank",
"code": "blank"
}
]
}{
"errors": [
{
"status": "429",
"title": "Too Many Requests",
"detail": "You've hit the create tracking requests limit. Please try again in a minute."
}
]
}Tracking Requests
Create a tracking request
To track an ocean shipment, you create a new tracking request.
Two attributes are required to track a shipment. A bill of lading/booking number and a shipping line SCAC.
Once a tracking request is created we will attempt to fetch the shipment details and it’s related containers from the shipping line. If the attempt is successful we will create in new shipment object including any related container objects. We will send a tracking_request.succeeded webhook notification to your webhooks.
If the attempt to fetch fails then we will send a tracking_request.failed webhook notification to your webhooks.
A tracking_request.succeeded or tracking_request.failed webhook notificaiton will only be sent if you have atleast one active webhook.
This endpoint is limited to 100 tracking requests per minute.
POST
/
tracking_requests
Create a tracking request
curl --request POST \
--url https://api.terminal49.com/v2/tracking_requests \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"data": {
"attributes": {
"request_type": "bill_of_lading",
"request_number": "MEDUFR030802",
"ref_numbers": [
"PO12345",
"HBL12345",
"CUSREF1234"
],
"shipment_tags": [
"camembert"
],
"scac": "MSCU"
},
"relationships": {
"customer": {
"data": {
"id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
"type": "party"
}
}
},
"type": "tracking_request"
}
}
'import requests
url = "https://api.terminal49.com/v2/tracking_requests"
payload = { "data": {
"attributes": {
"request_type": "bill_of_lading",
"request_number": "MEDUFR030802",
"ref_numbers": ["PO12345", "HBL12345", "CUSREF1234"],
"shipment_tags": ["camembert"],
"scac": "MSCU"
},
"relationships": { "customer": { "data": {
"id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
"type": "party"
} } },
"type": "tracking_request"
} }
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
data: {
attributes: {
request_type: 'bill_of_lading',
request_number: 'MEDUFR030802',
ref_numbers: ['PO12345', 'HBL12345', 'CUSREF1234'],
shipment_tags: ['camembert'],
scac: 'MSCU'
},
relationships: {customer: {data: {id: 'f7cb530a-9e60-412c-a5bc-205a2f34ba54', type: 'party'}}},
type: 'tracking_request'
}
})
};
fetch('https://api.terminal49.com/v2/tracking_requests', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.terminal49.com/v2/tracking_requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'attributes' => [
'request_type' => 'bill_of_lading',
'request_number' => 'MEDUFR030802',
'ref_numbers' => [
'PO12345',
'HBL12345',
'CUSREF1234'
],
'shipment_tags' => [
'camembert'
],
'scac' => 'MSCU'
],
'relationships' => [
'customer' => [
'data' => [
'id' => 'f7cb530a-9e60-412c-a5bc-205a2f34ba54',
'type' => 'party'
]
]
],
'type' => 'tracking_request'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.terminal49.com/v2/tracking_requests"
payload := strings.NewReader("{\n \"data\": {\n \"attributes\": {\n \"request_type\": \"bill_of_lading\",\n \"request_number\": \"MEDUFR030802\",\n \"ref_numbers\": [\n \"PO12345\",\n \"HBL12345\",\n \"CUSREF1234\"\n ],\n \"shipment_tags\": [\n \"camembert\"\n ],\n \"scac\": \"MSCU\"\n },\n \"relationships\": {\n \"customer\": {\n \"data\": {\n \"id\": \"f7cb530a-9e60-412c-a5bc-205a2f34ba54\",\n \"type\": \"party\"\n }\n }\n },\n \"type\": \"tracking_request\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.terminal49.com/v2/tracking_requests")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"attributes\": {\n \"request_type\": \"bill_of_lading\",\n \"request_number\": \"MEDUFR030802\",\n \"ref_numbers\": [\n \"PO12345\",\n \"HBL12345\",\n \"CUSREF1234\"\n ],\n \"shipment_tags\": [\n \"camembert\"\n ],\n \"scac\": \"MSCU\"\n },\n \"relationships\": {\n \"customer\": {\n \"data\": {\n \"id\": \"f7cb530a-9e60-412c-a5bc-205a2f34ba54\",\n \"type\": \"party\"\n }\n }\n },\n \"type\": \"tracking_request\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.terminal49.com/v2/tracking_requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"attributes\": {\n \"request_type\": \"bill_of_lading\",\n \"request_number\": \"MEDUFR030802\",\n \"ref_numbers\": [\n \"PO12345\",\n \"HBL12345\",\n \"CUSREF1234\"\n ],\n \"shipment_tags\": [\n \"camembert\"\n ],\n \"scac\": \"MSCU\"\n },\n \"relationships\": {\n \"customer\": {\n \"data\": {\n \"id\": \"f7cb530a-9e60-412c-a5bc-205a2f34ba54\",\n \"type\": \"party\"\n }\n }\n },\n \"type\": \"tracking_request\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "ba4cb904-827f-4038-8e31-1e92b3356218",
"type": "tracking_request",
"attributes": {
"request_number": "MEDUFR030802",
"request_type": "bill_of_lading",
"scac": "MSCU",
"ref_numbers": [],
"created_at": "2020-04-04T16:13:35-07:00",
"updated_at": "2020-04-04T17:13:35-07:00",
"status": "pending",
"failed_reason": null
},
"relationships": {
"tracked_object": {
"data": null
},
"customer": {
"data": {
"id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
"type": "party"
}
}
},
"links": {
"self": "/v2/tracking_requests/ba4cb904-827f-4038-8e31-1e92b3356218"
}
}
}{
"errors": [
{
"status": "422",
"source": {
"pointer": "/data/attributes/scac"
},
"title": "Unprocessable Entity",
"detail": "Scac can't be blank",
"code": "blank"
},
{
"status": "422",
"source": {
"pointer": "/data/attributes/scac"
},
"title": "Unprocessable Entity",
"detail": "Scac 'XXXX' is not recognized",
"code": "blank"
},
{
"status": "422",
"source": {
"pointer": "/data/attributes/scac"
},
"title": "Unprocessable Entity",
"detail": "Scac 'UALC' is not supported. We do not currently integrate with Universal Africa Lines",
"code": "blank"
},
{
"status": "422",
"source": {
"pointer": "/data/attributes/request_number"
},
"title": "Unprocessable Entity",
"detail": "Request number can't be blank",
"code": "blank"
}
]
}{
"errors": [
{
"status": "429",
"title": "Too Many Requests",
"detail": "You've hit the create tracking requests limit. Please try again in a minute."
}
]
}Don’t know the SCAC? Call Auto-Detect
Carrier first
to identify the shipping line from your tracking number.
Authorizations
Token YOUR_API_TOKEN
The APIs require authentication to be done using header-based API Key and Secret Authentication.
API key and secret are sent va the Authorization request header.
You send your API key and secret in the following way:
Authorization: Token YOUR_API_KEY
Body
application/json
Create a shipment tracking request
Show child attributes
Show child attributes
Was this page helpful?
⌘I