Check out frequently asked questions and guides on our product.

Contact an Integration Consultant by email

What Are APIs?

Put simply, APIs allow two or more systems to share data with each other, giving you new ways to consume and interact with your shipments and supply chain. APIs allow users to search for specific types of data, take action, or be notified of changes in status. Due to the real-time nature of APIs and the ability to centralize data from multiple systems, users of APIs can make decisions with the latest data, reducing delay and guess work. You likely interact with APIs every day; they are used by your car, television, phone, and smart home devices. APIs are used to integrate systems together for improved responsiveness, by exchanging information real-time.

When Should I Use a Union Pacific API?

When determining where to best use APIs, you should first start by identifying what data would be most useful to have real-time access to, within your system. Today, you may be manually looking up the latest information on a shipment from our website, or check if a service issue (or case) has been updated. Second, you should think about the actions you take to manage your shipments, like such as release, order in, etc. Using an API in these scenarios can get you the data you need, when you need it, and give you the ability to act upon it without having to leave your own system. While Union Pacific will be releasing our first suite of services later this year, we plan on continuing to add new functionality and services through additional releases.

What Are the Benefits of APIs?

API integrations make it easier for you to access your information and take the actions you need to do business. Integrating with Union Pacific API services allows you to

  • reduce manual work
  • streamline your rail processes
  • optimize your supply chain
  • expand the reach of your data

What will be included in the latest version of services released?

Building Blocks for Specification Review

Union Pacific’s API services are structured in data objects, or building blocks. These objects can be used as stand-alone services or combined to create more robust processes. In specification review, our team will work with you and help discuss ways you could use these services in your business.

  • Shipment – The shipment interface give the requestor the ability to search their active shipments by a variety of filters and get latest details on ETA/ETG, Planned UP Events, and Offline Events.
  • Shipment Actions – The shipment actions interface will give the request the ability to order in, release, cancel, and view request history for a customer’s location. 
  • Case – The case interface gives the requestor the ability to find the latest details on cases related to their shipment.
  • Equipment – The equipment interface gives the requester the ability to search through and identify equipment based on the equipment specifications.
  • Location – The location interface gives the requestor the ability to receive details about their company facilities on the Union Pacific network.
  • Account – The account interface gives the requester the ability to receive the latest details about their company or companies under their account hierarchy.
  • Waybill - The waybill interface gives the requestor the ability to lookup waybill details for a single waybill or multiple waybills.
  • Intermodal APIs – These API services will focus on the processes in the intermodal space including gate reservation and driver applications (UPGo).
  • General Services – The General Services interface allows the users to track active shipments for ETA and current location information.

What Are the Types of APIs?

As you look through our documentation you will see two different styles of APIs: resource (/shipment) and RPC (/releaseShipment). These styles are used to simplify the use and interaction with our APIs. The resource style APIs are used primarily for data reading and exploration. This style allows the caller to search through data and understand the relationship between it. The relationship between data should follow a logical business model (e.g., locations have tracks, and tracks have equipment). This helps with discovery and makes it easier to find the data you need. RPC style APIs are best used for taking action. The naming of these APIs mirrors this with a style. An example use case of these two styles used together occurs when a customer searches through rail cars to easily find the cars that they would like to order in to their industry.

What Systems Should I Integrate with APIs?

APIs are primarily used to connect two different systems together for transactional business. Some common implementations are integrating our APIs with your TMS (Transportation Management System), WMS (Warehouse Management System), or ERP Enterprise Resource Planning) system. It can also be useful to integrate historical data APIs into you analytics tool to evaluate and analyze historical performance. A good example of this includes analyzing historical shipment data to identify trends or determine monthly performance.

How Do I Get an API Client ID and Password?

Customers that want to integrate must first acquire an API Client ID. Provisioning one of these is similar to registering for a new web user account. The difference is, instead of providing this ID to a person for them to login to our website, the API Client ID is provided for your company to use in your software to identify your systems to Union Pacific. The API Client ID is required to authorize your requests access to data that Union Pacific provides through the APIs. It is important to keep the API Client ID and its corresponding password secure. You can request an API Client ID on our website. To do this, you must first have a user ID and password with MyUPRR.com. Once the API Client ID has been authorized, you will receive a password. Additional roles and authorized locations can be requested to be added to the ID on our website and will be verified with our data security team.

How Do I Integrate with Union Pacific?

Developers that want to use Union Pacific APIs will need to write a client that calls the API. The client will need to make an https request, called an Oauth token service, and parse Json data. These are common tasks for modern programming languages.

Every call to an API service has three parts:

  • A service name
  • A request
  • A response

The name of the API service is the specific operation that your program is trying to invoke. That operation might be to retrieve some information or it might be a request to perform some action.

The service request contains the service name and all of the data required for the service to perform the operation. The request is sent to the Union Pacific API server. Once the API server has received the request it will perform the operation and return a response. The response will contain data requested by your program. Responses will also indicate the status of a call. If there was an error, an error message will be returned to help you diagnose the problem. Otherwise the response will contain either the data you requested or an indication of the action you performed was successful.

The first thing your program must do is request a token from a special service called the token service. Your program will use the API Client ID and password to call the Oauth token service and acquire a token. Tokens are a one-time unique key that allows your program to call all other API services. Requesting a token is conceptually similar to logging into a website before using a website. Union Pacific APIs use the token to authenticate the identity of your program and ensure any data you retrieve or actions you perform should be are authorized. It is a good idea to cache the token and reuse it again. Tokens last for a matter of hours. When the token service returns the token, it will also return the expiration time for the token. When your token expires you may request a new one from the token service using your API Client ID and password.

What are your API Service Specifications (OpenAPI)?

An API service specification is a document that describes in detail all the possible data elements that are part of the request and response for each service. The specification will help you understand what the services do and how each service works. A developer can use the specification to ensure they are sending all the right data in the request. It also helps you to sort out determine which services you'll want to call in order to accomplish the goals for your program. Our API is documented using an industry standard specification format called OpenAPI (formerly known as Swagger). Developers that understand OpenAPI specifications may have an easier time learning what an API can do and how to use it. If you are not familiar with OpenAPI we provide user-friendly web pages that contain the information you will need.