Getting Started

Click the links below to jump to a section:

• Frequently Asked Questions
• Events & References
• API Structure
• Registration
• Rate Limiting

Frequently Asked Questions

What do I need to do to integrate the API?

The API does require integration and configuration:

• Register for credentials with Expeditors

• Business analysis within your organization to identify which API calls address your information needs

• Set up the API requests for the information you want to receive

• Integrate the data into business or reporting applications to be surfaced to end users in a meaningful way

How does the API compare with other exp.o Visibility options?

For what time frame is shipment information available?

The source data contains information for active shipments, as well as shipments completed in the last 120 days. It is the same source data that is used by the exp.o Visibility online application.

Do I have to search by a shipment number, or can I use a different reference number?  

The Shipment Count and Shipment List requests can be executed with or without reference numbers, or any trace reference can be used.  If no reference number is specified, the results include all shipments; if a reference value is specified, the results include only shipments with values matching the reference. Shipment Details, Events, References and Exact Match all require a specific shipment number.

What information is included?

Shipment Count provides a count of shipments for the organization in active status, or completed in the last 120 days.  If no reference number is specified, the count returned is for all shipments; if a reference value is specified, the count is only for shipments with values matching the reference.

Shipments returns Shipment ID, Status, Origin, Destination and Last Update Time.  If no reference number is specified in the request, information is returned for all shipments; if a reference value is specified, the summary is only for shipments with values matching the reference.

Shipment Detail returns the following information for a single Shipment ID, if the data is present on the shipment.

The Events request returns the same events as exp.o Visibility.

The References request returns the following information for a single Shipment ID, if the reference is present on the shipment:

• Reference Type

• Reference Number

See Event Codes & References fore more details.

The Exact Match request returns the shipment detail, events and references for a single shipment ID.

What shipment statuses are displayed?

To effectively segment stages of the shipment life cycle, a status is assigned based on the occurrence of specific core events:

• Shipment Logged - Pending Receipt

• Booked with Expeditors

• Documents Received at Origin

• Freight Received

• Freight and Docs Received

• Export Customs Submitted

• Export Customs Completed

• Booked with Carrier

• Cleared for Import, not Arrived at Frontier

• In Transit

• In Transit, Docs Received at Destination

• Brokerage Services Requested

• Docs Received at Destination

• Pending Customer's Broker

• Import Customs Entry Prepared

• Missing Information to Complete Entry

• Able to Complete Import Entry

• Import Customs Released

• Clearance Received

• Import Customs Released, Awaiting Arrival

• Trucker Notified; Pending Arrival

• Turned Over to Customer's Trucker; Pending Arrival

• Arrived: not Cleared Border Consignment

• Arrived: Pending Docs

• Arrived

• Arrived, Awaiting Customs Release

• Arrived, Pending Client's Broker

• Arrived and Released by Customs

• Trucker Notified

• Ready for Delivery

• Turned Over to Customer's Trucker

• Delivered

• Services Completed: Confirmed on Board

• Services Completed: Arrived

• Services Completed: Turned Over to Client Broker

• Services Completed: Turned Over to Client Trucker

• Services Completed: Delivered

• Services Completed: Customs Cleared

• Services Completed: Picked Up

• Services Completed: Export Customs Completed

• Services Completed: ISF Completed

• Services Completed: Distribution Billed

• Services Completed: Supplemental Decl. Accepted

• Other Government Agency Hold

• On Hold, Pending Information

• Cancelled

What time zone is used?

All date/time information uses UTC (Coordinated Universal Time)

Can I have multiple tokens active at the same time?

Yes, requesting new tokens will not impact previously issued tokens so you can have

multiple tokens active at the same time.  This is beneficial if you have a multi-server

environment.

Can I get a separate set of credentials for production and development?

Yes, please have your Expeditors contact request additional credentials.

Can a token ever expire early?

There are some corner case scenarios where tokens may “expire” early. For instance,

if a server goes down before it is able to persist the token to our data store. Our

recommendation is to continue to use a token until a call fails with an “invalid

token” response, at which point a new token can be requested and the failed call

can be reissued.

How can I tell if a shipment has departed?

There are two main ways.  First, you can look at the status of the shipment.  If

the status is “in transit” then you know the shipment has departed.  Second, you

can look for the COB event (confirmed on board) which provides actual departure information.

Why do I see multiple COB events?

Expeditors will have a COB event for each leg of the shipment.  For example, the

shipment could go from New York to Paris to Cairo so you will see a COB event from

New York to Paris and another COB event from Paris to Cairo.  The same is true for

our BKD event (booked to depart) which captures the planned departure information

for each leg of the shipment.

What if I get an error and it’s not in your list of error codes?

Our documentation only lists the common errors that we have configured.  A full list

of possible REST API error responses can be found here:  https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

How is the API structured?

All requests to this service must:

• Use the base URL https://api.expeditors.com/tracking/v2

• Append one of the documented URL endpoints with the specified HTTP method (GET, POST, etc)

• Substitute a valid value where the URL has a {variable} showing in curly braces

Request parameters and parameter values are case-sensitive.

Data is returned in JSON format.

Some URLs support optional parameters, such as sizeLimit={sizeLimit}&offset={offset}. Optional parameters are identified by an "N" for no in the "Required?" column of the Request Parameter table.

Registration

Contact your Expeditors representative to request credentials; the following information is required:

• Organization Name
• Customer Business Contact Name
• Customer Business Contact Email Address
• Customer Technical Contact Name
• Customer Technical Contact Email Address

We collect business and technical contact information for the purpose of notifying API users of system maintenance, downtimes and new releases. It is important to keep this information up-to-date with Expeditors to ensure timely notification of activities impacting the API.

For more information, see Notifications.

Rate Limit