API is a web connection that allows one software program to communicate with another, exchanging data between the two systems. When you integrate with XPO via our REST-based APIs, you can automate & customize access to our services from your own internal application or website.

API Integration Benefits

• Modern technology increases the speed of data transfer, resulting in time savings and increased efficiency
• Ability to customize the content and service you use most
• Access to LTL rating and shipment data in real-time
• Enhancements and new functionality available with version upgrades

Authentication

Users are required to register on the web and subscribe to the API. LTL APIs use the OAuth 2.0 protocol for authentication and authorization. All API requests must be made over SSL.

The API consumers are given an access token, which is the base 64 encoded value of consumer key and consumer secret. These tokens are unique to a user and must be stored securely. Also, the access tokens may expire at any time in the future.

The access tokens are used to generate the bearer token, which is a temporary token to invoke the business API.

To generate the bearer token, the user should make a POST request to https://api.ltl.xpo.com/token.

The Header parameter must contain the following:

• Authorization Basic <access token>

The body must contain the following as x-www-form-urlencoded values:

• grant_type = password
• username = <xpo ltl registered user id>
• password = <password>

The response message will contain bearer access token (bolded) that should be used to make the Business API call.

{
"access_token": "b4ab05082c47fb9628028a8c92a3f24e",
"refresh_token": "fb87136c2e472d450d9c3e89283e4d40",
"scope": "default",
"token_type": "Bearer",
"expires_in": 43200
}

Access Token is valid for 12 hours; Refresh token is valid for 24 hours. Once the Access Token is expired, the Refresh Token can be used to generate a new pair of Access and Refresh Tokens.

Scopes: Each access token has a scope that defines what it can do and what resources it can access. In most cases, the user will be granted basic access. In cases where the user is not authorized to access a resource, the user will receive an error message.

Rate Limits

The rate limits for XPO LTL APIs are controlled separately for each access token and on a sliding one-minute window.

Health Check

Every API comes with a health check to see if the API is functioning.

The health-check service can be called by adding the resource: health-check.

If you want to check if the Pickup Request API is running for example, make a GET request to https://api.ltl.xpo.com/pickuprequest/1.0/health-check (replace pickuprequest with the API name). The response would look like this:

{
"code": 200,
"transactionTimestamp": 1472754590484,
"data": "Service LTL-PickupRequest-API is running"
}

Options

The Options call will list all the available resources that are supported in the API. To get this list, make a GET request to (replace pickuprequest with the API name) https://api.ltl.xpo.com/pickuprequest/1.0/options.

Structure

Each response is a standard structure contained in an envelope, so you can expect a standard set of key values. The envelope contains the following keys in the following order:

1. code
2. transactionTimestamp
3. data
4. error
5. link

code contains the standard http status codes and indicates the success or failure of the API. Success status codes are: 200, 201, 204, 301, and 303.

transactionTimestamp contains the system timestamp of the API execution.

data contains the actual response business object. If there are exceptions, the error will be populated with the exceptions thrown by the API.

error — error codes are set as follows along with the fault error message:

• 400 – Bad Request
• 404 – Not found
• 304 – Not Modified
• 409 – Conflict
• 415 – Unsupported Media Type

Note: We are currently supporting JSON and XML formats for this API.

link – Currently, links are populated for the Options call only. In the future, the links section will also contain the hypermedia links for business objects.

XML Usage

XML Request Structure

The request call to the API operation should be made in the format

<operationName xmnls=”http://www.ltl.xpo.com/API/APIName”>
For example, a call to the calculateTransitTime operation in the LTLShippingToolsAPI API would appear as:
<?xml version="1.0" encoding="UTF-8"?>
<calculateTransitTimeRqst
		xmlns="http://www.ltl.xpo.com/API/LTLShippingToolsAPI">
  …
</calculateTransitTimeRqst>
	

Testing & Test Mode

When subscriptions are completed, any REST API testing client can be used to test the integration.

Test Mode

Pickup Request and Bill of Lading API operations have a test mode, so you can perform testing. This is a mandatory field. If set to Y, then the request will be routed to a test system (the requests will not be forwarded to a service center). If set to N, then the request will be routed to production.

To test, please follow this format by adding the testMode parameter (replace billoflading with the appropriate API name):

https://api.ltl.xpo.com/billoflading/1.0/billsoflading?testMode=Y

For calls to the production environment, please use the following format:

https://api.ltl.xpo.com/billoflading/1.0/billsoflading?testMode=N

APIs currently available:

Ready to get started?

If you are ready to integrate with our APIs, please send an email to LTLWebAPISupport@xpo.com and include the following information

• Your Web User ID - if you don't have one, you can register here
• List of the REST API integrations you want
• What type of API Consumer are you (ex: Direct Customer, 3PL, Broker, TMS Provider, Service Provider...etc)?
• If you are connecting through a TMS or Service Provider, which one?
• Which XPO LTL integration method are you using today? (ex: XML, EDI)?

Once we receive your email, a member of our API Support Team will contact you to get started.