Create an Application
Each application is a unique set of API keys and configuration settings needed for making requests to Ryder's APIs.
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
The TM Shipment API is used by carriers to update Ryder on load status and location in real time. By integrating this API, carriers can:
Send shipment status updates (e.g., Picked Up, Delivered).Push GPS location data at 15-minute intervals.Subscribe to event notifications for key status changes.
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:
Go to the Ryder Developer Portal and sign up.
Check your email for a verification message from no_reply@ryder.com and click "Verify."
Log in and navigate to My Account > My Apps.
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."
Review and accept the Developer Terms of Service.
Notify your Ryder contact that you have requested access.
Upon approval, you will receive an email from developer_notifications@ryder.com.
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.1Host: api.ryder.comOcp-Apim-Subscription-Key: your_api_key_hereAccept: 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) – Record actual status updates (asynchronous processing).Shipments(/shipments) – Push GPS location data (every 15 minutes).Loads(/loads) – Push GPS location data (every 15 minutes).Load Status(/loads/ship-status) – Record actual status updates (asynchronous processing).Load Confirmation(/loads/confirmation) – Push GPS location data (every 15 minutes).Event Notifications(/notification-preferences) – Subscribe to status update 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 anywarningsorerrorsthat 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.1Host: api.ryder.com/fmsOcp-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.1Host: api.ryder.com/fmsOcp-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.1Host: api.ryder.com/fmsOcp-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.