Getting Started with the TM Shipment API 

The TM Shipment API enables third-party carriers to record location updates and milestone events for active loads. This guide provides an overview of how to authenticate, access endpoints, and integrate the API into your system.

View the API Reference for detailed specifications. 

How It Works

By integrating with Ryder's TM Shipment API, customers can:

• Manage Shipments: Initiate shipment requests, update shipment details, and cancel shipments as needed.

• Receive Load Information: Get shipment consolidation details and load updates through the Load API.

• Confirm Shipment Execution: Notify Ryder when a shipment has left the yard via the Ship Confirmation API.

• Track Shipment and Load Status: Request real-time shipment progress and location updates with the Ship Status API.

API Workflow

The diagram below illustrates how customers interact with Ryder’s systems, including which APIs to use at different stages of the shipment lifecycle.

Getting Access

To use the TM Shipment API, complete testing in the Test Environment before moving to Production. Follow the steps below to request access:

1. Go to the Ryder Developer Portal and sign up.

2. Check your email for a verification message from no_reply@ryder.com and click "Verify."

3. Log in and navigate to My Account > My Apps.

4. Create an application with the following details:

   • App Name: Your company and app name.

   • OAuth Redirect URL: Leave blank.

   • API Product: Select "TM Shipment Management API."

5. Review and accept the Developer Terms of Service.

6. Notify your Ryder contact that you have requested access.

7. Upon approval, you will receive an email from developer_notifications@ryder.com.

8. Retrieve your Production API Key in My Account > My Apps. Your Test Key will be provided separately by Ryder.

Authentication

The TM Shipment API uses Okta authentication for secure access. All requests require an API key, which should be included in the request headers:

POST /scs/tmshipment/v1/loads/{loadId} HTTPS/1.1 
Host: api.ryder.com 
Ocp-Apim-Subscription-Key: your_api_key_here
Accept: application/json

Endpoint Overview

For the full API specification, see the API Reference. The TM Shipment API consists of the following endpoints:

• Shipment Requests (/shipments/requests) – Submit, update, or cancel shipment requests (async processing).

• Shipments (/shipments) – Manage shipment details and status updates.

• Loads (/loads) – Receive load plan details and shipment consolidation updates.

• Load Status (/loads/ship-status) – Request real-time load and shipment status updates (async processing).

• Load Confirmation (/loads/confirmation) – Confirm load departure to trigger tracking.

• Event Notifications (/notification-preferences) – Subscribe to real-time shipment and load status notifications.

Event Types

The following shipment events trigger API notifications and updates:

Status Code   Status Description     Shipment   Load
------------------------------------------------------
1             Open                   x          x
2             Picked Up              x          x
3             Delivered              x          x
4             Closed                 x          x
5             Cancelled              x          x
6             Planned                -          x
7             Tendered               -          x
8             Tender Accepted        -          x
9             Tender Rejected        -          x
10            Hold                   x          -
11            Approved               x          -
12            Declined               x          -
13            Draft                  x          -
14            Hold_For_Review        x          -
15            Error                  x          x
16            In_Queue               x          x
17            Lights_Out_Draft       x          -
18            Partial Picked Up      x          x
19            Partial Delivered      x          x
20            On Load                x          x
21            Delete                 x          x

Payload Content

What You Can Expect from Notifications

Once you’ve subscribed to specific events, the notifications will contain the following key details:

• Transaction Type: The type of transaction being monitored ("Shipment" or "Load).

• Event: The event that triggered the shipment or load notification (e.g., "Delivered", "Cancelled").

• Resource Link: A link to the resource that was affected by the event.

• Timestamp: When the event occurred.

• Event Messages: Depending on the event, additional details may be included, such as any warnings or errors that occurred.

Sample Email Notification Example

Here is an example of an email notification:

Use Cases

Use Case 1: Retrieve All Vehicles for a Customer 

A customer wants to retrieve a list of all vehicles they have access to. They can use the ‘GET /vehicles’ endpoint with their customer number as a query parameter. 

GET /vehicles?customerNumber=23456 HTTPS/1.1 
Host: api.ryder.com/fms 
Ocp-Apim-Subscription-Key: your_api_key_here 

Use Case 2: Retrieve a Specific Vehicle by VIN 

A customer needs details about a specific vehicle identified by its VIN. They can use the ‘GET /vehicles’ endpoint with the VIN as a query parameter. 

GET /vehicles?vin=3ALACXFC3LDLZ3143 HTTPS/1.1 
Host: api.ryder.com/fms 
Ocp-Apim-Subscription-Key: your_api_key_here 

Use Case 3: Retrieve a Vehicle by Vehicle Number 

A customer needs detailed information about a specific vehicle. They can use the ‘GET /vehicles/{vehicleNumber}’ endpoint with the vehicle number. 

GET /vehicles/277686 HTTPS/1.1 
Host: api.ryder.com/fms 
Ocp-Apim-Subscription-Key: your_api_key_here 

Troubleshooting & FAQs

Common Issues and Solutions

• Authentication failure:
  Ensure you are using the correct API key for the appropriate environment (Test vs. Production) and following the Okta authentication flow.

• The /shipments/requests endpoint is not returning an immediate response:
  This endpoint is asynchronous, so check the status of the request by polling the corresponding shipment request ID.

• I want to reuse an externalCustomerNumber, but I'm getting an error:
  The same externalCustomerNumber can only be reused if the existing shipment request with that number has been moved to Cancelled.

Verifying API Requests

Test API request validity by sending a sample request with a known valid payload and verifying the response status code and message.

Frequently Asked Questions

• How do I know which events will trigger an update?
  Review the Event Types section to see which shipment and load statuses trigger updates.

• Can I resubmit a shipment request with the same externalCustomerNumber?
  Yes, but only if the previous shipment request with that number has been cancelled.

• Why is my authentication request failing?
  Confirm that you are passing the correct API key in the request header and that your authentication token is valid.

• How do I check the status of an asynchronous request?
  Poll the shipment request ID using the appropriate status endpoint to check for updates.

Additional Resources

• API Reference

• Contact Support