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"
  }
}
'

{
  "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"
    }
  }
}

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"
  }
}
'

{
  "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"
    }
  }
}

Authorizations

Authorization

string

header

required

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

data

object

Show child attributes

data.type

enum<string>

required

Available options:

tracking_request

data.attributes

object

Show child attributes

data.attributes.request_type

enum<string>

required

The type of document number to be supplied. Container number support is currently in BETA.

Available options:

bill_of_lading,

booking_number,

container

Example:

"bill_of_lading"

data.attributes.request_number

string

required

Example:

"MEDUFR030802"

data.attributes.scac

string

required

Required string length: 4

Example:

"MSCU"

data.attributes.ref_numbers

string[]

Optional list of reference numbers to be added to the shipment when tracking request completes

data.attributes.shipment_tags

string[]

Optional list of tags to be added to the shipment when tracking request completes

data.relationships

object

Show child attributes

data.relationships.customer

object

Show child attributes

data.relationships.customer.data

object

Show child attributes

data.relationships.customer.data.id

string<uuid>

data.relationships.customer.data.type

enum<string>

Available options:

party

Response

Tracking Request Created

data

Tracking Request · object

Show child attributes

data.id

string<uuid>

required

data.type

enum<string>

required

Available options:

tracking_request

data.attributes

object

Show child attributes

data.attributes.request_number

string

required

Example:

"ONEYSH9AME650500"

data.attributes.status

enum<string>

required

Available options:

pending,

awaiting_manifest,

created,

failed,

tracking_stopped

data.attributes.request_type

enum<string>

required

Available options:

bill_of_lading,

booking_number,

container

Example:

"bill_of_lading"

data.attributes.scac

string

required

Required string length: 4

Example:

"ONEY"

data.attributes.created_at

string<date-time>

required

data.attributes.ref_numbers

string[] | null

data.attributes.tags

string[]

data.attributes.failed_reason

enum<string> | null

If the tracking request has failed, or is currently failing, the last reason we were unable to complete the request

Available options:

booking_cancelled,

duplicate,

expired,

internal_processing_error,

invalid_number,

not_found,

retries_exhausted,

shipping_line_unreachable,

unrecognized_response,

data_unavailable,

data.attributes.updated_at

string<date-time>

data.attributes.is_retrying

boolean

data.attributes.retry_count

integer | null

How many times T49 has attempted to get the shipment from the shipping line

data.relationships

object

Show child attributes

data.relationships.tracked_object

object

Show child attributes

data.relationships.tracked_object.data

object

Show child attributes

data.relationships.tracked_object.data.id

string<uuid>

data.relationships.tracked_object.data.type

enum<string>

Available options:

shipment

data.relationships.customer

object

Show child attributes

data.relationships.customer.data

object

Show child attributes

data.relationships.customer.data.id

string<uuid>

data.relationships.customer.data.type

enum<string>

Available options:

party

included

(Account model · object | Shipping line model · object)[]

Account model
Shipping line model

Show child attributes

included.id

string<uuid>

required

included.type

enum<string>

required

Available options:

container

included.attributes

object

required

Show child attributes

included.attributes.company_name

string

required

List tracking requests Get a single tracking request

⌘I

Getting Started

In Depth Guides

Useful Info

Shipments

Tracking Requests

Webhooks

Webhook Notifications

Containers

Shipping Lines

Metro Areas

Ports

Vessels

Terminals

Parties

Create a tracking request

Authorizations

Body

Response