Rating API - User Manual

Rating API

User Manual

1
2
2
2
2
3
4
4
4
4
4
5
5
5
6
6
6
7
Rating API Manual
Table of Contents
Notices
Rating API Rules
Business Processes and Rules
Rating Ground Freight Rules
Negotiated Rates
TForce Freight Density Rates
Introduction
About the TForce Freight Rating API
Who Should Read This Manual
Manual Organization
Prerequisites
Getting Started with Rating API
Key Steps to Begin
Helpful Resources
Rating API Endpoints
OpenAPI Metadata
Get Rate
Volume Rating

8
8
8
8
9
15
17
18
19
19
22
23
31
31
Making a Request
Base URL
Headers
Query Parameters
Details for /getRate Endpoint
Details for /volumeRating Endpoint
Details for /openapi Endpoint
API Throttling
Rating API Response Structure and Codes
Rating Response Body Properties
Formatting and Common Element Constraints
Property details
Application Integration and Testing
Using Negotiated Rates in CIE

32
32
34
34
34
35
35
35
36
37
37
38
38
38
39
Appendix
Frequently Asked Questions (FAQ)
HTTP Response Codes
Response Status Codes
Service Codes
Rate Codes
Pickup Codes
Delivery Codes
Packaging Type Codes
Billing Codes
Call Type Codes
Freight Classifications
Country Codes
Canadian Province and Territory Codes
US State Codes

Notices

This section contains important legal and regulatory information that governs the use of TForce Freight

APIs. By accessing or using the API, you agree to comply with the terms outlined in this section. Please

take a moment to review the following notices before proceeding.

The content and materials provided in this documentation are the property of TForce Freight and are

protected by applicable copyright laws. All rights are reserved. You may use the documentation for your

internal purposes related to using this TForce Freight API, but you may not reproduce, distribute, modify,

or otherwise exploit the content for commercial purposes without express written consent from TForce

Freight.

Trademarks

"TForce Freight" and the TForce Freight logo are trademarks or registered trademarks of TForce Freight

in various jurisdictions. Other names, logos, and trademarks appearing in this documentation are the

property of their respective owners.

Your use of this TForce Freight API is subject to the TForce Freight Terms of Use, which can be accessed

on our official website. By using the API, you acknowledge that you have read, understood, and agreed to

abide by the Terms of Use.

API Usage Policies

Please note that the use of this TForce Freight API is subject to specific usage policies, which may

include rate limits, acceptable use guidelines, and data usage restrictions. These policies are designed to

ensure fair and responsible use of the API and to maintain the quality of service for all users. Be sure to

review and adhere to these policies to avoid any disruptions to your API access.

Legal Disclaimers

The information and materials provided in this documentation are for informational purposes only and are

provided "as is" without any warranties, expressed or implied. TForce Freight makes no representations

or warranties regarding the accuracy, completeness, or suitability of the information contained herein.

TForce Freight disclaims any liability for any errors or omissions in the documentation.

Privacy Policies

Your privacy is important to us. TForce Freight's privacy practices are outlined in our Privacy Policy, which

can be accessed here on our official website. The Privacy Policy describes how we collect, use, disclose,

and safeguard your personal information in connection with the use of our services, including this API.

Attribution Requirements

If you are a third-party developer using this API to provide services to your clients, you may need to

adhere to certain attribution requirements as specified by TForce Freight.

Contact Information

For inquiries related to this API, its usage, or any other matter, please contact our support team at

[email protected].

Rating API Manual June 07, 2024

Rating API Rules

The TForce Freight Rating API gives client applications a way to determine the rates available for a

ground freight shipment. To use this service, an application sends TForce Freight details about the

shipment such as its origin, destination, and contents as well as the specific TForce Freight service

desired.

Business Processes and Rules

TForce Freight expects schema as defined in the request structure i.e., no spelling or structural

deviations. Elements that are not defined in the data request will result in request being rejected.

Only users that plan to ship packages manifested, tendered, and delivered by TForce Freight can

use the API.

Any customers/developers abusing or data mining the API will have their access revoked.

To access API documentation, users must be have a registered TForce Freight profile and be

logged in.

To access testing and production sites, users must have OAuth Credentials and be enrolled as an

API End User. For more details, see our website to help you get started.

Rating Ground Freight Rules

The Rating API cannot be used to access rates or data from proprietary rate basing systems or

licensed products that are not the property of TForce Freight. The Rating Ground Freight API may

not be used by brokers or resellers of transportation services.

Ground Freight does not offer void, label recovery, or return services.

Ground Freight does not offer Paperless Invoice.

Users must be registered with a user ID and password for TFF API portal in order to see

Negotiated Rates. For additional information, refer to the TFF API portal instructions for negotiated

rates guide in the Developer Kit.

All shipping and billing locations must be included in the Ground Freight registration.

Requests for utilizing the Rating API with data from proprietary rate basing systems or licensed

products that are not the property of TFI International Inc. can only be considered after approval

from the owning authority. Upon application for access to the Rating API, TForce Freight will

request approval from the owning authority prior to completing the application request.

The Rating API may only be used by brokers or resellers of transportation services with a current

and active TForce Freight agreement/partnership. The Shipping and Pickup APIs are the products

of TForce Freight and are available to all customers.

Negotiated Rates

To view negotiated rates for Ground Freight rates please contact your Account Executive.

Users must be registered with a user ID and password for the Developer Portal and have an approved

TForce Freight Account Number to see Negotiated Rates.

Rating API Manual June 07, 2024

TForce Freight Density Rates

TForce Freight Rates, Density Based Rating (DBR), provide a new rating method based on dimensional

weight for the TForce Freight Less Than Truckload (LTL) and UPS® Ground with Freight Pricing* (GFP)

customers who ship using the Shipping API – Ground.

Rating API Manual June 07, 2024

Note: *TForce Freight is an authorized reseller of UPS® Ground with Freight Pricing but is not

authorized to resell any other services offered by United Parcel Service, Inc. or its affiliates.

Introduction

Welcome to the TForce Freight Rating API Manual. This comprehensive guide is designed to assist

developers use the TForce Freight Rating API to access and calculate shipping rates. Whether you are

building applications to enhance customer experience or streamline internal operations, this manual will

provide you with the knowledge to seamlessly integrate with TForce Freight’s rating services.

About the TForce Freight Rating API

The TForce Freight Rating API offers a powerful set of endpoints that allow you to retrieve detailed

shipping rates based on various parameters such as shipment size, weight, and destination. By

integrating our API into your applications, you can provide your users with precise and real-time shipping

rate calculations.

Who Should Read This Manual

This manual is intended for developers, software engineers, and technical teams who are responsible for

integrating the TForce Freight Rating API into their applications. Whether you are new to APIs or an

experienced developer, this guide will provide you with the necessary information to get started and make

the most out of TForce Freight’s rating capabilities.

Manual Organization

To help you navigate this manual, we’ve outlined the following sections that cover different aspects of the

TForce Freight Rating API:

Notices: Important legal and disclaimer information.

Introduction: An overview of the manual's purpose and organization.

Getting Started with the TForce Freight Rating API: Guidelines on accessing the API, including

authentication, base URLs, and versioning.

Rating API Endpoints: A detailed exploration of the available rating endpoints, their specific

functions, and guidelines for effective utilization.

Request and Response Format: Information about the structure of API requests and responses,

including headers, URL formats, and data formats.

Integration and Testing Guidelines: Recommendations for testing your integration, including a

testing environment, sample data, and rate limiting considerations.

Appendix: Additional resources, including error codes, enumerations, and additional reference

materials.

Prerequisites

Before you proceed, it's recommended that you have a basic understanding of HTTP, API concepts, and a

programming language you intend to use for API integration. Additionally, you should have an active

TForce Freight developer account and the necessary credential approval to access the API endpoints.

Please reach out to the TForce Freight API support team if you have any questions or need assistance

during the integration process.

Rating API Manual June 07, 2024

Getting Started with Rating API

TForce Freight APIs allow for seamless third-party integrations, enabling TForce Freight customers to

enroll their accounts with your application and access/update their account information.

Key Steps to Begin

The following is a high level overview of the client registration and authorization process:

1. User Onboarding: Users can sign up for a new TForce Freight account or log into an existing one.

Once enrolled, they'll grant consent for your application to access their TForce Freight account

data. This process is managed by the TForce Freight Customer Identity and Access Management

(CIAM) platform.

2. Configuring Your Application: Visit your developer portal profile to configure your application

settings:

Set up your application's display information (e.g., logo, display name, home page URL).

Provide a webhook URL for receiving events from the TForce Freight API.

Manage your OAuth client secrets for secure exchanges.

3. Handling Webhook Events: Upon user consent, an event (UserOnboardedEvent) will be

dispatched to your configured webhook. This event contains essential information about the

onboarded user, which you can use to make further requests to the TForce Freight Tracking API.

4. Token Management: Use the provided JSON Web Token (JWT) from the UserOnboardedEvent to

retrieve access and refresh tokens from the TForce Freight CIAM platform. These tokens are

essential for accessing user data through the API.

5. Accessing the API: With a valid token, you can then access the TForce Freight API to retrieve or

update the onboarded user's data.

6. Recovering Access Rights: If tokens expire, users will need to reaffirm their consent. To

streamline this process, consider implementing a mechanism to refresh tokens before they expire.

Helpful Resources

For more detailed and technical guides on integrating with the TForce Freight API, visit the TForce Freight

Developer Portal and see our resource pages.

Additional references:

Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow

Overview of the Microsoft Authentication Library (MSAL)

CloudEvents

Rating API Manual June 07, 2024

GET /openapi

POST /getRate

Rating API Endpoints

The TForce Freight Rating API offers endpoints for calculating shipping rates based on various

parameters like service options, shipment details, and commodities. This section provides an overview of

the main endpoints available for use.

This overview highlights the key rating endpoints offered by the TForce Freight Rating API. Each endpoint

serves a specific purpose, providing different ways to calculate and retrieve rate information. Detailed

information on utilizing these endpoints can be found throughout this manual.

OpenAPI Metadata

Description:

This endpoint provides the OpenAPI metadata for the TForce Freight Rating API, detailing the

available endpoints, request and response formats, and other crucial API information.

Request Details

Get Rate

Description:

This endpoint allows for retrieving shipping rates based on detailed request parameters. These

include service codes, pickup dates, shipping locations (ship from, ship to, and payer), service

options, and commodities details.

Request Body Description:

The request must include detailed information such as requestOptions (like service code, pickup

date, etc.), ship from, ship to, payment, service options, and commodities. Each part has specific

required fields like addresses, billing codes, and packaging types.

Request Details

Rating API Manual June 07, 2024

POST /volumeRating

Volume Rating

Description:

The Volume Rating endpoint is designed for obtaining shipping rates for large-volume or less-than-

truckload (LTL) freight shipments. It caters to scenarios where the shipment size is substantial and

requires special handling or rate calculation.

Request Body Description:

The request must encompass details such as requestOptions (like service code and pickup date),

shipFrom and shipTo addresses, serviceOptions, and commodity details (linear feet, weight, etc.).

This endpoint is particularly relevant for larger shipments where the total volume and weight

significantly influence the rate estimation.

Request Details

Rating API Manual June 07, 2024

https://api.tforcefreight.com/rating

Making a Request

This section focuses on the specifics of making a request to the TForce Freight Rating API, including

required headers, parameters, and the format of the request body.

Base URL

The following URL allows you to access the TForce Freight Rating API Endpoints:

Production

Headers

Below is a table of the headers supported and required by the API:

Header Name Description Req? Example Value

Authorization

Used for passing the OAuth2.0

access token.

REQ (for

authenticated

endpoints)

Bearer [Access-

Token]

Cache-Control Directive for caching mechanism. OPT no-cache

Acceptable content type for

responses.

OPT application/json

Content-Type

The media type of the body of the

request (used with POST, PUT and

PATCH).

REQ (for requests

with a body)

application/json

Query Parameters

Below is a table of the query parameters supported by the API:

Parameter Name Description Req? Example Value

api-version

Specifies the version of the API to use.

'v*' (e.g., v1) for live production

'cie-v*' (e.g., cie-v1) for customer

integration environment matching the

production version

'cie-vNext' for testing upcoming versions

Please visit the APIs page for available versions.

REQ

v1, cie-v1, cie-

vNext

Rating API Manual June 07, 2024

Note: It is critical to understand the way versioning is handled through query parameters. Review

the section on testing environments for an example of the version query parameter in use.

Details for  /getRate  Endpoint
This endpoint allows for retrieving shipping rates based on various parameters.
Request Body Properties
The request body must include detailed information such as requestOptions (service code, pickup date,
etc.), shipFrom, shipTo, payment, serviceOptions, and commodities.
Property Name Type Description
Example
Value
requestOptions Object
Container for request option
information.
{ }
requestOptions.serviceCode String
The service code associated with
the shipment.
'308'
requestOptions.pickupDate String Date of the Pickup. '2024-03-29'
requestOptions.type String
Rating Call Type. Possible values:
`L`.
'L'
requestOptions.densityEligible Boolean
Indicates whether the rate request
is eligible for density-based pricing.
false
requestOptions.timeInTransit Boolean
Indicates if Time in Transit
information is requested and will be
returned.
true
requestOptions.quoteNumber Boolean
Indicates if a Quote Number will be
returned for this LTL Freight Rate
quote request.
true
requestOptions.customerContext String
Contextual information provided by
the customer for the request.
'REF123456'
shipFrom Object Origin information container. { }
shipFrom.address Object
Origin location information
container.
{ }
shipFrom.address.city String Shipper's city. Richmond
shipFrom.address.stateProvinceCode String Shipper’s state or province code. VA
shipFrom.address.postalCode String Shipper’s postal code. 23224
shipFrom.address.country String Shipper’s country code. US
shipFrom.isResidential Boolean
Indicates that the shipment requires
a residential pickup.
false
Rating API Manual June 07, 2024
© 2024 TFI International Inc. All Rights Reserved. Confidential and Proprietary Page 9

Property Name Type Description
Example
Value
shipTo Object
Destination information
container.
{ }
shipTo.address Object
Destination location information
container.
{ }
shipTo.address.city String Destination (consignee's) city. "Richmond"
shipTo.address.stateProvinceCode String
Destination (consignee's) state
or province code.
"VA"
shipTo.address.postalCode String
Destination (consignee's) postal
code.
"23224"
shipTo.address.country String
Destination (consignee's)
country code.
"US"
shipTo.isResidential Boolean
Indicates that the shipment
requires a residential delivery.
false
payment Object
Container for information about
the payment.
{ }
payment.payer Object
Container for information about
the payer.
{ }
payment.payer.address Object
Container for information about
the payer's location.
{ }
payment.payer.address.city String Payer's city. Richmond
payment.payer.address.stateProvinceC
ode
String Payer’s state or province code. VA
payment.payer.address.postalCode String Payer's postal code. 23224
payment.payer.address.country String Payer's country code. US
payment.billingCode String Shipment Billing code. 30
serviceOptions Object Service options for the shipment. { }
serviceOptions.pickup
Array of
Strings
Shipment Pick up service
options.
['INPU',
'LIFO']
serviceOptions.delivery
Array of
Strings
Shipment delivery service
options.
['INDE',
'LIFD']
Rating API Manual June 07, 2024
© 2024 TFI International Inc. All Rights Reserved. Confidential and Proprietary Page 10

Property Name Type Description
Example
Value
serviceOptions.shipment Object
Includes properties for
freezableProtection, extremeLength,
adjustedHeight, sortAndSegregate, and
excessValue.
{ }
serviceOptions.shipment.freezableProte
ction
Boolean
Indicates whether freezable protection
is required.
true
serviceOptions.shipment.extremeLengt
h
Object
Container indicating the shipment
contains an item of extreme length.
{ }
serviceOptions.shipment.extremeLengt
h.value
String
Indicates the shipment contains an item
of extreme length. Dimensional length
of the article(s) given in feet.
'15'
serviceOptions.shipment.extremeLengt
h.unit
String
Unit of measurement for extreme
length, default is FEET.
'FEET'
serviceOptions.shipment.adjustedHeigh
t
Object Adjusted height container. { }
serviceOptions.shipment.adjustedHeigh
t.value
String Adjusted height value. '10'
serviceOptions.shipment.adjustedHeigh
t.unit
String
Unit of measurement for the adjusted
height.
'IN'
serviceOptions.shipment.sortAndSegre
gate
Object
Information on units for
sorting/segregation.
{ }
serviceOptions.shipment.sortAndSegre
gate.quantity
Number
Quantity of units to be
sorted/segregated.
5
serviceOptions.shipment.excessValue Object
Information container for excess value
information.
{ }
serviceOptions.shipment.excessValue.v
alue
String Excess value amount. '1000'
serviceOptions.shipment.excessValue.c
urrency
String
Excess value amount currency type.
Valid value: USD - United States Dollar.
'USD'
Rating API Manual June 07, 2024
© 2024 TFI International Inc. All Rights Reserved. Confidential and Proprietary Page 11

Property Name Type Description
Example
Value
commodities
Array of
Objects
List of commodities information for
the shipment. Must have at least 1
item and can have up to 100.
[ { } ]
commodities[].class String Freight Classification. '100'
commodities[].nmfc Object Container for NMFC information. { }
commodities[].nmfc.prime String
National Motor Freight Classification
Commodity prime code. Consists of 6
digits representing the NMFC prime
Code.
'123456'
commodities[].nmfc.sub String
National Motor Freight Classification
Commodity sub code. Consists of 2
digits representing the NMFC sub
Code.
'01'
commodities[].pieces Integer
Number of pieces of the commodity in
the handling unit.
1
commodities[].weight Object
Container for the weight of the
commodity.
{ }
commodities[].weight.weight Number
The value for the line item weight
associated with the shipment.
200
commodities[].weight.weightUnit String
Commodity Weight Unit Of
Measurement. Accepts 'LBS' for
pounds.
'LBS'
commodities[].packagingType String
TForce Freight packaging type
associated with the shipment. See
the appendix.
'BAG'
commodities[].dangerousGoods Boolean
Indicates that the commodity is of
type dangerous goods.
true
commodities[].dimensions.length Number
The length of the line item used to
determine dimensional weight. Max
value: 324 inches.
10
Rating API Manual June 07, 2024
© 2024 TFI International Inc. All Rights Reserved. Confidential and Proprietary Page 12

Property Name Type Description
Example
Value
commodities[].dimensions.width Number
The width of the line item used to
determine dimensional weight. Max
value: 96 inches.
15
commodities[].dimensions.height Number
The height of the line item used to
determine dimensional weight. Max
value: 102 inches.
20
commodities[].dimensions.unit String
The code associated with the unit of
measure for the line item.
'inches'
handlingUnits
Array of
Objects
List of handling unit information for
the shipment.
[ ]
handlingUnits[].pieces Integer
Handling Unit Quantity for Density
based rating.
1
handlingUnits[].weight Object
Container for the weight of the
handling unit.
{ }
handlingUnits[].weight.weight Number
Handling unit weight value for the
shipment.
250
handlingUnits[].weight.weightUnit String
Unit of Measurement for the Handling
unit weight. Accepts 'LBS' for pounds.
'LBS'
handlingUnits[].packagingType String
Packaging Types for the Handling
Unit. See the appendix.
'PLT'
handlingUnits[].dangerousGoods Boolean
Indicates that the commodity in the
handling unit is of type dangerous
goods.
true
handlingUnits[].dimensions Object
Container for the dimensions of the
handling unit.
{ }
handlingUnits[].dimensions.length Number
The length of the line item in the
handling unit used to determine
dimensional weight. Maximum 324
inches.
40
handlingUnits[].dimensions.width Number
The width of the line item in the
handling unit used to determine
dimensional weight. Maximum 96
inches.
48
handlingUnits[].dimensions.height Number
The height of the line item in the
handling unit used to determine
dimensional weight. Maximum 102
inches.
60
handlingUnits[].dimensions.unit String
Unit of measurement for the
dimensions of the handling unit.
Accepts 'IN' for inches.
'IN'
Rating API Manual June 07, 2024
© 2024 TFI International Inc. All Rights Reserved. Confidential and Proprietary Page 13

Property Name Type Description

Example

Value

ShipmentTotalWeight Object

Container for the total weight of the

shipment.

{ }

ShipmentTotalWeight.weight Number Total weight of the shipment. 500

ShipmentTotalWeight.weightUnit String

Unit of measurement for total shipment

weight. Accepts 'LBS' for pounds.

'LBS'

HandlingUnitWeight Object

Container for the weight of the

handling unit.

{ }

HandlingUnitWeight.weight Number Weight of the handling unit. 250

HandlingUnitWeight.weightUnit String

Unit of measurement for the handling

unit weight. Accepts 'LBS' for pounds.

'LBS'

Rating API Manual June 07, 2024

Details for  /volumeRating  Endpoint
This endpoint allows for retrieving shipping rates on large volumes.
Request Body Properties
The request body must include detailed information such as requestOptions (service code, pickup date,
etc.), shipFrom, shipTo, payment, serviceOptions, and commodities.
Property Name Type Description
Example
Value
requestOptions.serviceCode String
The code for the TForce Freight
Service associated with the
shipment. For Volume Rating, only
code `308` is allowed.
'308'
requestOptions.pickupDate Date
Date of the Pickup in YYYY-MM-DD
format.
'2023-08-28'
requestOptions.type String
Rating Call Type. Possible Values in
V1 - L
'L'
requestOptions.timeInTransit Boolean
Indicates if Time in Transit
information is requested and will be
returned.
true
requestOptions.quoteNumber Boolean
Indicates if a Quote Number will be
returned for this LTL Freight Rate
quote request.
true
requestOptions.customerContext String
Contextual information provided by
the customer for the request.
'REF123456'
shipFrom.address.city String Shipper's city. Richmond
shipFrom.address.stateProvinceCode String Shipper’s state or province code. VA
shipFrom.address.postalCode String Shipper’s postal code. 23224
shipFrom.address.country String Shipper’s country code. US
shipFrom.isResidential Boolean
Indicates that the shipment requires
a residential pickup.
false
shipTo.address.city String Consignee's city. "Richmond"
shipTo.address.stateProvinceCode String Consignee’s state or province code. "VA"
shipTo.address.postalCode String Consignee’s postal code. "23224"
shipTo.address.country String
Consignee's country code. See
appendix.
"US"
shipTo.isResidential Boolean
Indicates that the shipment requires
a residential delivery.
false
Rating API Manual June 07, 2024
© 2024 TFI International Inc. All Rights Reserved. Confidential and Proprietary Page 15

Property Name Type Description Example Value
serviceOptions.pickup
Array of
Strings
Shipment Pick up service
options. See appendix.
['INPU', 'LIFO']
serviceOptions.delivery
Array of
Strings
Shipment delivery service
options. See appendix.
['INDE', 'LIFD']
serviceOptions.shipment Object
Includes properties for
freezableProtection,
extremeLength, adjustedHeight,
sortAndSegregate, and
excessValue.
{}
serviceOptions.shipment.freezableProte
ction
Boolean
Indicates whether freezable
protection is required
true
serviceOptions.shipment.extremeLengt
h.value
String
Indicates the shipment contains
an item of extreme length.
Dimensional length of the
article(s) given in feet.
'15'
serviceOptions.shipment.extremeLengt
h.unit
String
Unit of measurement for
extreme length, default is FEET.
'FEET'
serviceOptions.shipment.sortAndSegre
gate.quantity
Number
Quantity of units to be
sorted/segregated
5
serviceOptions.shipment.excessValue.v
alue
String Excess value amount '1000'
serviceOptions.shipment.excessValue.c
urrency
String
Excess value amount currency
type. Valid value: USD - United
States Dollar
'USD'
commodity[]
Array of
Objects
Details of the commodities
included in the shipment
[{...}]
commodity[].linearfeet String
Linear Feet of the commodity
for volume calculation
'44'
commodity[].pieces Integer
Number of pieces of the
commodity in the handling unit
3
commodity[].weight Object Weight of the commodity
{ "weight":
10000,
"weightUnit":
"LBS" }
commodity[].weight.weight Number Weight value of the commodity 10000
commodity[].weight.weightUnit String Weight unit of the commodity 'LBS'
commodity.dangerousGoods Boolean
Indicates whether dangerous
goods are included.
false
Rating API Manual June 07, 2024
© 2024 TFI International Inc. All Rights Reserved. Confidential and Proprietary Page 16

Property Name Type Description

Example

Value

commodity[].packagingType String

TForce Freight packaging type

associated with the shipment. See the

appendix.

'BAG'

Details for /openapi Endpoint

This endpoint provides the OpenAPI metadata for the Rating API and does not require a request body,

specific headers, or parameters.

Rating API Manual June 07, 2024

API Throttling

TForce Freight APIs implement throttling mechanisms to ensure equitable distribution of resources among

all users and to safeguard the system's stability and reliability. This section clarifies the different throttling

policies in place.

Rate Limiting

Our system implements rate limiting when a large volume of requests is received in a short time frame.

This limiting helps balance server load and maintain consistent performance even during traffic spikes.

Renewal Time: 60 seconds.

High request volumes may result in a 429 error response. This indicates that there's a temporary hold on

requests to ensure optimal experience for all users. The rate limit resets after 60 seconds.

Quota Limiting

Different from rate limiting, quota limiting controls the number of requests an individual user can send

over an extended period. Quota limiting ensures no single user overwhelms the system. Each user has a

generous request allowance for this time frame.

Renewal Time: 300 seconds.

Crossing the quota limit threshold will trigger a 403 error response for the user who exceeded the limit.

This error is exclusive to the user who has exceeded their quota, and normal access is restored after 300

seconds.

Summary of Throttle Limits

The following table summarizes the different throttling limits.

Throttle Type Error Code Renewal Time User Affected

Rate Limit 429 60 seconds All users

Quota Limit 403 300 seconds Requesting user only

Recommendations

The following recommendations will help you manage your API requests to minimize throttling.

Continuously monitor your API usage.

If you receive a 429 or 403 response, consider implementing a method like exponential back-off for

your requests. Wait for the specified renewal time before sending another batch of requests.

Review the HTTP header of our responses. It can offer insights about your current usage relative

to potential limits.

Rating API Manual June 07, 2024

Note: Customer Integration Environment (CIE) endpoints and Production endpoints maintain

separate throttling counters. Reaching a limit in one environment won’t impact your request

allowance in the other.

Rating API Response Structure and

Codes

The following section details the various codes and responses you may receive from the Rating API.

Rating Response Body Properties

These tables summarize and describe the different response body properties you may encounter.

Understanding These Tables

These tables represent nested JSON structures using dots to denote parent structures.

For example, consider the following field from our table:

summary.responseStatus.code

This corresponds to the nested structure in the JSON response:

{

"summary": {

"responseStatus": {

"code": "OK"

}

In the response, the

code

is nested within

responseStatus

which itself is nested within

summary

Hence, the dot notation

summary.responseStatus.code

Rating Response Properties

The response properties are the same for both GetRate and VolumeRating endpoints

Property Type Description

summary object Summary of the rating operation result.

summary.responseStatus object Object containing the response status.

summary.responseStatus.code string

The response code indicating the result of the

rating operation.

summary.responseStatus.message string

The descriptive message corresponding to the

response code.

summary.transactionReference object

Object containing the transaction reference

details.

summary.transactionReference.transactionId string The unique identifier for the rating transaction.

summary.classDensityIndicatior string Indicates the conversion code of the rates.

Rating API Manual June 07, 2024

Property Type Description

summary.quoteNumber string

The Quote Number returned in the response associated

to the specific LTL Freight Rate returned in the response.

summary.minimumChargesApplied boolean

The presence of the tag indicates the rate returned has a

minimum charge applied to it.

summary.customerContext string

The Customer Context Information which will be echoed

during response.

summary.isRegisteredUser boolean Indicated whether the user is registered or not.

summary.publishedRates boolean Indicates when the published rates are returned.

detail array

An array of details for each item in the rate request. All

applicable services will be returned for each call.

detail[].detailStatus object

Object containing the status details for the individual

rate.

detail[].detailStatus.code string The code indicating the status of the rate detail.

detail[].detailStatus.message string The message describing the detail status code.

detail[].alerts[] array

An array of rate items, each containing a code,

description, value, and unit.

detail[].alerts[].code string The code for the specific rate type.

detail[].alerts[].message string A text description of the rate type.

detail[].service object

Object containing information about the service

associated with the shipment.

detail[].service.code string

The code representing the specific TForce Freight

Service for the shipment.

detail[].service.description string

A description of the TForce Freight Service related to the

service code.

detail[].rate array

An array of rate items, each containing a code,

description, value, and unit.

detail[].rate[].code string The code for the specific rate type.

detail[].rate[].description string A text description of the rate type.

detail[].rate[].value number The numeric value of the rate.

detail[].rate[].unit string The unit of measure for the rate, typically currency.

detail[].commodities array An array of commodities included in the rate detail.

detail[].commodities[].description string Description of the commodity.

Rating API Manual June 07, 2024

Property Type Description

detail[].commodities[].weight object

Object containing weight details of the

commodity.

detail[].commodities[].weight.weight string The actual weight of the commodity.

detail[].commodities[].weight.adjustedWeight string

The adjusted weight of the commodity, if

applicable.

detail[].commodities[].weight.weightUnit string The unit of weight measurement.

detail[].shipmentCharges object

Object containing the total charges for the

shipment.

detail[].shipmentCharges.total object

Object containing the total value and currency of

the shipment charges.

detail[].shipmentCharges.total.value string The total charge value for the shipment.

detail[].shipmentCharges.total.currency string

The currency code for the total shipment

charges.

detail[].shipmentWeights object

Object containing information about the shipment

weights.

detail[].shipmentWeights.billable object

Object containing the billable weight of the

shipment.

detail[].shipmentWeights.billable.value string The billable weight value for the shipment.

detail[].shipmentWeights.billable.unit string

The unit of measurement for the billable weight

(e.g., LBS).

detail[].serviceCenter object Object containing service center details.

detail[].serviceCenter.origin.code string Code for the origin service center.

detail[].serviceCenter.origin.name string Full name of the origin service center.

detail[].serviceCenter.destination.code string Code for the destination service center.

detail[].serviceCenter.destination.name string Full name of the destination service center.

detail[].ratedAs[].class string Freight Classification.

detail[].ratedAs[].weight string Weight value for the class.

detail[].timeInTransit object

Object containing the time in transit for the

shipment.

detail[].timeInTransit.value string

The value representing the time in transit for the

shipment.

detail[].timeInTransit.unit string

The unit of measurement for the time in transit

(e.g., DAY).

Rating API Manual June 07, 2024

Formatting and Common Element

Constraints

Understanding the constraints on data elements is crucial when integrating with the TForce Freight Rating

API. This section outlines common element constraints specific to this API.

Data Types

The Rating API utilizes various data types, including:

String: Used for textual data such as names, email addresses, codes, and other descriptive

information.

Integer: Represents numeric values without decimals, used for properties like pieces and weight.

Boolean: Indicates true/false values.

Array: A collection of elements, often used for lists like 'service options' and 'email notifications'.

Object: Represents complex data structures that can contain multiple properties.

Value Constraints

Certain elements have specific constraints. For example:

Service Code: Must be one of the specified enumeration values (e.g., '308', '309').

Review the appendix and property tables for additional enumerations.

Length and Format Constraints

Some string values have specific formats or patterns they must adhere to.

Date

The date format follows the ISO 8601 standard. The date should be in the format YYYY-MM-

DD. Example: 2024-12-31.

Time

The time format uses a 24-hour clock. The time should be in the format HHMM. Example:

1300 for 1:00 PM or 0930 for 9:30 AM.

Postal

Code

The postal code format must match typical postal codes used in the US, Canada, and

Mexico. Example: US - 12345, Canada - A1A1A1, Mexico - 12345.

Also note:

Weight Unit: Must be a valid unit (e.g., 'LBS' for pounds).

Dimensional Units: Length, width, and height units must be consistent and valid (e.g., 'inches',

'feet').

Rating API Manual June 07, 2024

Note: Adhering to these constraints is essential for successful API requests. Ensure that your

requests conform to these guidelines for effective integration with the TForce Freight Rating API.

Property details

The following section details constraints for each property.

Details for /getRate requests

{

"requestOptions": {

Req: Yes

"serviceCode": "",

Req: Yes

Enum: Appendix

"pickupDate": "",

Req: Yes

Format: Date

"type": "",

Req: Yes

Enum: Appendix

"densityEligible": ,

Req: Opt

Enum: Boolean

"timeInTransit": ,

Req: Opt

Enum: Boolean

"quoteNumber": ,

Req: Opt

Enum: Boolean

"customerContext": "",

Req: Opt

"shipFrom": {

Req: Yes

"address": {

Req: Yes

"city": "",

Req: Opt

"stateProvinceCode": "",

Req: Opt

Characters: =2

"postalCode": "",

Req: Yes

Format: Postal Code

Rating API Manual June 07, 2024

Note: The "Req" field denotes whether each property is required (Yes), conditionally required

(Con), or optional (Opt). Required properties must always be included in requests. Conditionally

required properties must be included if their parent property is included. Optional properties can

either be included or excluded in your requests.

Details for /getRate requests (cont)

"country": "",

Req: Yes

Enum: Appendix

"isResidential": ,

Req: Opt

Enum: Boolean

"shipTo": {

Req: Yes

"address": {

Req: Yes

"city": "",

Req: Opt

"stateProvinceCode": "",

Req: Opt

Characters: =2

"postalCode": "",

Req: Yes

Format: Postal Code

"country": "",

Req: Yes

Enum: Appendix

"isResidential": ,

Req: Opt

Enum: Boolean

"payment": {

Req: Yes

"payer": {

Req: Yes

"address": {

Req: Yes

"city": "",

Req: Opt

"stateProvinceCode": "",

Req: Opt

Characters: =2

"postalCode": "",

Req: Yes

Format: Postal Code

"country": "",

Req: Yes

Enum: Appendix

}

"billingCode": "",

Req: Yes

Enum: Appendix

Rating API Manual June 07, 2024

Details for /getRate requests (cont)

}

"serviceOptions": {

Req: Opt

"pickup": [ "" ],

Req: Opt

Items Allowed: ≥0

Enum: Appendix

"delivery": [ "" ],

Req: Opt

Items Allowed: ≥0

Enum: Appendix

"shipment": {

Req: Opt

"freezableProtection": ,

Req: Opt

Enum: Boolean

"extremeLength": {

Req: Opt

"value": "",

Req: Con

Value: >0

"unit": ""

Req: Con

Enum: FEET

"adjustedHeight": {

Req: Opt

"value": "",

Req: Con

Value: >0

"unit": ""

Req: Con

Enum: FEET

"sortAndSegregate": {

Req: Opt

"quantity": ,

Req: Con

"excessValue": {

Req: Opt

"value": "",

Req: Con

"currency": ""

Req: Con

Enum: USD

Rating API Manual June 07, 2024

Details for /getRate requests (cont)

}

"commodities": [

Req: Yes

Items Allowed: ≥1 and ≤100

{

"class": "",

Req: Opt

Enum: Appendix

"nmfc": {

Req: Opt

"prime": "",

Req: Opt

Characters: =6

"sub": ""

Req: Opt

Characters: =2

}

"pieces": ,

Req: Yes

Value: ≥1 and ≤9999

"weight": {

Req: Yes

"weight": ,

Req: Yes

Value: ≥0

"weightUnit": ""

Req: Yes

Enum: `LBS` - Pounds

}

"packagingType": "",

Req: Yes

Enum: Appendix

"dangerousGoods": ,

Req: Opt

Enum: Boolean

"dimensions": {

Req: Opt

"length": ,

Req: Con

Value: ≥0 and ≤324

"width": ,

Req: Con

Value: ≥0 and ≤96

"height": ,

Req: Con

Value: ≥0 and ≤102

Rating API Manual June 07, 2024

Details for /getRate requests (cont)

"unit": ""

Req: Con

Enum: `IN` - Inches

}

"handlingUnits": [

Req: Opt

Items Allowed: ≥0

{

"pieces": ,

Req: Con

Value: ≥1 and ≤9999

"weight": {

Req: Opt

"weight": ,

Req: Con

Value: ≥0

"weightUnit": ""

Req: Con

Enum: `LBS` - Pounds

"packagingType": "",

Req: Con

Enum: Appendix

"dangerousGoods": ,

Req: Opt

Enum: Boolean

"dimensions": {

Req: Con

"length": ,

Req: Con

Value: ≥0 and ≤324

"width": ,

Req: Con

Value: ≥0 and ≤96

"height": ,

Req: Con

Value: ≥0 and ≤102

"unit": ""

Req: Con

Enum: `IN` - Inches

}

"shipmentTotalWeight": {

Req: Opt

Rating API Manual June 07, 2024

Details for /getRate requests (cont)

"weight": ,

Req: Opt

Value: ≥0

"weightUnit": ""

Req: Opt

Enum: `LBS` - Pounds

"handlingUnitWeight": {

Req: Opt

"weight": ,

Req: Opt

Value: ≥0

"weightUnit": ""

Req: Opt

Enum: `LBS` - Pounds

}

Details for /volumeRating requests

{

"requestOptions": {

Req: Yes

"serviceCode": "",

Req: Yes

Enum: Appendix

"pickupDate": "",

Req: Yes

Format: Date

"timeInTransit": ,

Req: Opt

Enum: Boolean

"customerContext": "",

Req: Opt

"shipFrom": {

Req: Yes

"address": {

Req: Yes

"city": "",

Req: Opt

"postalCode": "",

Req: Yes

Format: Postal Code

Rating API Manual June 07, 2024

Details for /volumeRating requests (cont)

"country": "",

Req: Yes

Enum: Appendix

"isResidential": ,

Req: Opt

Enum: Boolean

"shipTo": {

Req: Yes

"address": {

Req: Yes

"city": "",

Req: Opt

"postalCode": "",

Req: Yes

Format: Postal Code

"country": "",

Req: Yes

Enum: Appendix

"isResidential": ,

Req: Opt

Enum: Boolean

"serviceOptions": {

Req: Opt

"pickup": [ ],

Req: Opt

Items Allowed: ≥0

Enum: Appendix

"delivery": [ ],

Req: Opt

Items Allowed: ≥0

Enum: Appendix

"shipment": {

Req: Opt

"freezableProtection": ,

Req: Opt

Enum: Boolean

"extremeLength": {

Req: Opt

"value": "",

Req: Con

Value: >0

Rating API Manual June 07, 2024

Details for /volumeRating requests (cont)

"unit": "",

Req: Con

Enum: FEET

"sortAndSegregate": {

Req: Con

"quantity": ,

Req: Yes

Value: >0

"excessValue": {

Req: Opt

"value": "",

Req: Con

"currency": "",

Req: Con

Enum: `USD`

}

"commodity": {

Req: Yes

"linearfeet": ,

Req: Yes

Value: ≥8 and ≤28

"pieces": ,

Req: Opt

"weight": {

Req: Yes

"weight": ,

Req: Yes

"weightUnit": "",

Req: Yes

Enum: `LBS` - Pounds

}

"dangerousGoods": ,

Req: Opt

Enum: Boolean

"packagingType": "",

Req: Opt

Enum: Appendix

}

Rating API Manual June 07, 2024

/rating/[endpoint]?api-version=cie-v1

/rating/[endpoint]?api-version=v1

Application Integration and Testing

TForce Freight's integration environment is available 24/7 for your application testing.

Integration Testing

For integration testing, please point your Rating RESTful API requests to:

CIE

Production Environment

Upon the conclusion of testing, redirect your Rating RESTful API to the following production URL:

Production

Using Negotiated Rates in CIE

The negotiated rates returned do not reflect the contractual rate. Typically the Negotiated Rates in CIE will

differ from your actual rates.

Additionally, the shipper eligibility for negotiated rates is not fully verified in the Customer Integration

Environment.

Rating API Manual June 07, 2024

Note: All API URLs are case-sensitive.

Appendix

Frequently Asked Questions (FAQ)

Category Question Answer

Rating

How can I view my TForce Freight

(TFF) negotiated rates?

To view your TFF negotiated rates, the postal

code must match the payer and the postal code

of the set-up account.

Fuel Surcharge

Is the Fuel Surcharge listed as a

separate line item in the response

for TFF Rating API?

Yes, the fuel surcharge is listed as a separate

line item within the response.

TForce Freight

Shipping

What are the supported TForce

Freight countries and territories?

TForce Freight country or territory origins include

US, CA & MX. Service for other territories is

available by contacting Customer Service.

Maximum

Shipment

Weight

What is the maximum shipment

weight for TForce Freight LTL?

The maximum weight for TForce Freight LTL is

19,999 lbs. Shipments 20,000 lbs. or over are

considered a Truckload (TL) movement.

Rating

Is Pallet Rating supported for

TForce Freight?

Pallet rating is not supported for online rating

with TForce Freight.

Rating

Does the API rate offshore

shipments for TForce Freight?

No, please contact Customer Service for

offshore rating.

Rating

Are there any rate structures that

are not allowable for TForce

Freight?

No.

Rating

Is 3rd Party or Freight Collect

available through the TForce

Freight Rating or Shipping APIs?

Yes, but only for the customer that is paying the

invoice. Others can create a Bill of Lading.

Rating

What rates can be returned using

the TForce Freight rating API?

Published rates based on the TForce Freight 560

tariff or a contract rate negotiated with TForce

Freight.

Rating

Can I choose the rate I want

returned in the rate request for

TForce Freight?

No, the API supports a single rate type based on

your setup with TForce Freight.

Time in Transit

Is Time in Transit available through

the TForce Freight Rating or

Shipping APIs?

Yes, Time in Transit is available and does not

include Weekends or Holidays.

Maximum

Linear Feet

What is the maximum Linear feet

allowed for TForce Freight LTL

Ground Freight?

The maximum dimensional length is 26 feet,

subject to change based on business rules.

Rating API Manual June 07, 2024

Category Question Answer

GF (LTL)

Rating

How can I add locations to

a contract with TForce

Freight?

Contact our Freight sales representative to add accounts

and locations to the negotiated rates.

General

Is phone support provided

for TForce Freight

Developer APIs?

Support will be provided via email at

[email protected].

Rating API Manual June 07, 2024

HTTP Response Codes

These are some of the HTTP status codes that the API may return in response to your requests:

Status

Code

Description Additional Info

200 OK The request was successful and returned the expected data.

400 Bad Request

The server could not understand the request due to invalid syntax. Check

your request body or parameters.

401 Unauthorized

The user is not authenticated. Ensure that your API key or authentication

token is valid.

403 Forbidden

When the user's request quota is exceeded. The response will include a

Retry-After header indicating the recommended retry interval in seconds.

This typically affects the requesting user only.

404 Not Found

The server could not find the requested endpoint or resource. Ensure your

URL is correct.

429

Too Many

Requests

The call rate for the API has been exceeded. The response will include a

Retry-After header indicating the recommended retry interval in seconds.

This affects all users.

Response Status Codes

Code Description

PRT Partial return.

OK Successful operation

NFO Rate not found.

Service Codes

Service Code Description

308 TForce Freight LTL (US/US, US/ CA)

309 TForce Freight LTL - Guaranteed

349 TForce Standard LTL (US/MX)

Rating API Manual June 07, 2024

Rate Codes

Code Description Example Value Unit

DSCNT Discount 0 USD

DSCNT_RATE Discount Rate 0 USD

INDE INSIDE_DL 169.0 USD

INPU INSIDE_PU 169.0 USD

RESP RESIDENTIAL_PU 207.0 USD

RESD RESIDENTIAL_DL 207.0 USD

LIFD LIFT_GATE_DL 175.0 USD

LIFO LIFT_GATE_PU 175.0 USD

FUS_FEE Fuel Surcharge Fee 249.45 USD

LND_GROSS LND_GROSS 588.32 USD

AFTR_DSCNT AFTR_DSCNT 588.32 USD

Pickup Codes

Code Description

WHPU Weekend Holiday Pickup

INPU Inside Pickup

RESP Residential Pickup

LIFO Liftgate Pickup

LAPU Limited Access Pickup

TRPU Tradeshow Pickup

Delivery Codes

Code Description

NTFN Notification Before Delivery

WHDL Weekend Holiday Delivery

INDE Inside Delivery

RESD Residential Delivery

LADL Liftgate Delivery

LIFD Limited Access Delivery

TRDS Tradeshow Delivery

Rating API Manual June 07, 2024

Packaging Type Codes

Handling Package Codes

Handling Code Description Handling Code Description

CY Cylinder CAR Carrier

SCN Screen LSE Lease

LOO Loose PAL Pail

OTH Other PLT Pallet

SKD Skid TOT Totes

CBY Carboy

Commodity Package Codes

Commodity Package Type Code Description

BAG Bag

BAL Bale

BAR Barrel

BDL Bundle

BIN Bin

BOX Box

BSK Basket

BUN Bunch

CAB Cabinet

CAN Can

CAR Carrier

CAS Case

CBY Carboy

CON Container

CRT Crate

CSK Cask

Rating API Manual June 07, 2024

Commodity Package Type Code Description

CTN Carton

CYL Cylinder

DRM Drum

LOO Loose

OTH Other

PAL Pail

PCS Pieces

PKG Package

PLN Pipe Line

PLT Pallet

RCK Rack

REL Reel

ROL Roll

SKD Skid

SPL Spool

TBE Tube

TNK Tank

UNT Unit

VPK Van Pack

WRP Wrapped

Billing Codes

Billing Code Description

10 Prepaid

30 Bill to Third Party

40 Freight Collect

Call Type Codes

Type Code Description

L LTL only

Rating API Manual June 07, 2024

Freight Classifications

Class Numbers Class Numbers Class Numbers Class Numbers

50 55 60 65

70 77.5 85 92.5

100 110 125 150

175 200 250 300

400 500

Country Codes

Country Abbreviation

Canada CA

Mexico MX

United States of America US

Canadian Province and Territory Codes

Province/Territory Abbreviation Province/Territory Abbreviation

Alberta AB Nunavut NU

British Columbia BC Ontario ON

Manitoba MB Prince Edward Island PE

New Brunswick NB Quebec QC

Newfoundland and Labrador NL Saskatchewan SK

Northwest Territories NT Yukon YT

Nova Scotia NS

Rating API Manual June 07, 2024

US State Codes

State Abbreviation State Abbreviation

Alabama AL Montana MT

Alaska AK Nebraska NE

Arizona AZ Nevada NV

Arkansas AR New Hampshire NH

California CA New Jersey NJ

Colorado CO New Mexico NM

Connecticut CT New York NY

Delaware DE North Carolina NC

Florida FL North Dakota ND

Georgia GA Ohio OH

Hawaii HI Oklahoma OK

Idaho ID Oregon OR

Illinois IL Pennsylvania PA

Indiana IN Rhode Island RI

Iowa IA South Carolina SC

Kansas KS South Dakota SD

Kentucky KY Tennessee TN

Louisiana LA Texas TX

Maine ME Utah UT

Maryland MD Vermont VT

Massachusetts MA Virginia VA

Michigan MI Washington WA

Minnesota MN West Virginia WV

Mississippi MS Wisconsin WI

Missouri MO Wyoming WY

Rating API Manual June 07, 2024