Skip to main content

​
Create a tracking request

The create tracking request endpoint allows you to initiate monitoring for ocean freight shipments. This endpoint accepts bill of lading numbers, or container numbers along with shipping line SCAC codes to begin tracking shipment progress.

​
Endpoint Overview

POST /tracking_requests This endpoint creates a new tracking request that will attempt to fetch shipment details from the specified shipping line.

​
Request Process

When a tracking request is created, the following process occurs:
  1. Request Validation: The API validates the tracking number and shipping line SCAC code
  2. Data Retrieval: The system attempts to fetch shipment data from the shipping line
  3. Status Update: The tracking request status is updated to reflect the outcome
  4. Webhook Notification: A webhook event is sent to notify of success or failure

​
Request Format

​
Headers

HeaderTypeRequiredDescription
X-API-KeystringYesYour API key for authentication
Content-TypestringYesMust be application/json

​
Request Body

{
  "data": {
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MEDUFR030802",
      "shipping_line_scac": "MSCU",
      "ref_numbers": [
        "PO12345",
        "HBL12345"
      ],
      "shipment_tags": [
        "camembert"
      ]
    },
    "type": "tracking_request"
  }
}

​
Required Parameters

ParameterTypeDescription
request_typestringType of tracking request: “bill_of_lading” or “container”
request_numberstringThe bill of lading number, or container number to track
shipping_line_scacstringThe SCAC code of the shipping line

​
Optional Parameters

ParameterTypeDescription
ref_numbersarrayArray of reference numbers associated with the shipment
shipment_tagsarrayArray of tags for categorizing shipments

​
Response Format

​
Success Response (201 Created)

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

​
Response Fields

FieldTypeDescription
data.idstringUnique identifier for the tracking request
data.typestringResource type (always “tracking_request”)
data.attributes.request_typestringType of tracking request
data.attributes.request_numberstringThe tracking number being monitored
data.attributes.shipping_line_scacstringThe SCAC code of the shipping line
data.attributes.ref_numbersarrayArray of reference numbers
data.attributes.shipment_tagsarrayArray of tags
data.attributes.created_atstringISO 8601 timestamp when created
data.attributes.updated_atstringISO 8601 timestamp when last updated
data.attributes.statusstringCurrent status (“pending”, “created”, “failed”)
data.attributes.failed_reasonstringReason for failure if failed, null otherwise

​
Status Codes

CodeDescription
201Tracking request created successfully
400Bad request - invalid parameters
401Authentication failed - invalid API key
422Validation error - check request parameters
429Rate limit exceeded

​
Tracking Request Types

The API supports two types of tracking requests:
  • bill_of_lading: Track shipments using bill of lading numbers
  • container: Track shipments using container numbers

​
Tracking Request Statuses

The tracking request can have the following statuses:
  • pending: The tracking request has been created and the system is attempting to fetch shipment data
  • created: The tracking request was successful and a shipment object has been created
  • failed: The tracking request failed to fetch shipment data

​
Webhook Events

When a tracking request is created, the following webhook events may be sent:
  • tracking_request.succeeded: Sent when shipment data is successfully retrieved
  • tracking_request.failed: Sent when the tracking request fails to fetch data