API quick start

Welcome to the Track123 API! This guide walks you through the essential steps to start using Track123's API,including:

1、obtain your API key

2、use a suite of powerful tools to create trackings and get tracking updates

Obtain your API key

Steps to get your API key:

Login to Track123's Admin Portal
Go to Developers > API
Copy and save your API key

Common use cases: create trackings and get tracking updates

Before you get started, click here to view API document.

In this section,we'll mainly look at the most important functions of Track123 API: Register a tracking and Get tracking updates.

Case1: register a tracking

By using Register tracking API, you can create/import tracking numbers to Track123 portal for our users, which is usually used together with "get API".

Use Register trackings API: https://api.track123.com/gateway/open-api/tk/v2/track/import

you can send an API request as below：

curl --request POST \
     --url https://api.track123.com/gateway/open-api/tk/v2/track/import \
     --header 'Track123-Api-Secret: Your_Track123_API_key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
[
  {
    "trackNo": "771700723045",
    "courierCode": "fedex"
  }
]
'

When registering a new tracking, we suggest you provide the tracking number and courier code. But if you don't have such info, you can skip it, and we will try to detect the courier for you.
How to get the carrier code:
- You can search for the desired courier in the Carriers List page. After opening a courier’s page, you can find the courier code in the URL of the page. For example, in the URL https://www.track123.com/carriers/japan-post, the courier code for Japan Post is japan-post.

You can also use the Get Carriers API to retrieve a list of couriers along with their official websites and courier codes.

Note that for some couriers, you may need to provide additional information, such as the postal code or phone number, along with the tracking number to retrieve the tracking details. For more information, please refer to this guide.
For importing a shipment, you can request it 3 times/s, 100 tracking numbers per request.

Now it's time to test your API key in the Register tracking page in the API document.

Navigate to reference->tracking->Register tracking

Fill in your API key in these two places

Enter the tracking number and courier code

click "Try it!" to view the response instantly.

Case2: get tracking updates

To get updated on the progress of your shipments, you may choose to make API calls or set up Webhook. (If you'd like to receive proactive notifications and avoid making superfluous API calls when tracking isn't updating, you should use Webhook.)

In this part, we'll guide you through how to use Tracking123's Webhook and API to get tracking updates.

Note that you have imported trackings by Register Trackings API, otherwise the following operation will be invalid.

Way1: via Get trackings API

Use Get trackings API: https://track123-api.readme.io/reference/get-package-trackings. You can retrieve the current status and checkpoints for tracking numbers.

Example Request:

curl --request POST \
     --url https://api.track123.com/gateway/open-api/tk/v2/track/query \
     --header 'Track123-Api-Secret: Your_Track123_API_key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "trackNos": [
    "123123122222"
  ]
}
'

For getting trackings, you can request it 5 times/s, 100 tracking numbers per request.
You can get tracking information including transitSubStatus, transitDays,stayDays,lastTrackingTime and so on.

Now you can follow these steps to test your API key in the page of Register tracking in the API document:

Navigate to reference->tracking->Register tracking

Enter tracking number

Click "Try it!" to view the response instantly.

Way2: via webhook

By setting up a webhook, you can receive updates whenever the status of a tracking number changes.

Follow these steps to set up your webhook:

Navigate to Webhook Settings

Log into your Track123 account and go to Developer > Webhook.Click 'Add Webhook'

Enter Your Endpoint URL

In the webhook settings, enter your server’s endpoint URL where you want to receive the status update notifications, and then click Save to confirm your webhook setup.

Receive Real-Time Updates

Once the webhook is set up, you will receive real-time notifications every time the tracking status of your parcels changes.