API Support and FAQ

You need the following:

• A public certificate issued to your company by a well-known Certificate Authority in x509 PEM format.  We do not accept certificates that are self-signed, private, or those issued by Let's Encrypt, webCARES or CloudFlare.com. The certificate begins with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----.
• A BNSF.com userid set up for your company (get one here). In general, only one ID is needed for your company.
• An email address that matches the company name on the certificate
• The Common Name field on the certificate should be consistent with the company associated with your BNSF.com userid and with the email address used to submit the registration.
• Letters of Authorization (LOA) from authorized companies in order to monitor their shipments. If you are not on the waybill, you need to be added in the ZS monitoring role when the waybill is created or by way of LOA. See "What is the ZS monitoring role and how do I get it?"

Any type of SSL/TLS certificate issued by any of the top Certificate Authorities will work. Except for Let's Encrypt, you can choose from any of the providers in the list on Wikipedia.

Any of the SSL/TLS certificates offered by the major Certificate Authorities is acceptable. See "What are the requirements to register for the BNSF Customer API?" for more details about requirements.

After you submit the Registration form, it can take up to five (5) business days to get setup. However, it is usually much faster than that. You will receive an email when the configuration is complete. If you have not received an email after five days, please use the Support information at the bottom of this page to let us know.

Use the Message Us tool, which can be found under Help in the  BNSF Customer Portal to submit an 'Application Programming Interface (API)' / 'Restricted Service' request. NOTE: Restricted Services are only available in the Production environment. You should get at least one unrestricted service working before requesting an environment change to Production via Message Us.

Some of the services in the BNSF Customer API are restricted. You can review the list on the Registration page. If you think you need access to a restricted service, use the Message Us tool, which can be found under Help in the BNSF Customer Portal.  There you can submit an 'Application Programming Interface (API)' / 'Restricted Service' request. NOTE: Restricted Services are only available in the Production environment. You should get at least one unrestricted service working before requesting an environment change to Production.

The certificate you use to authenticate with our API gateway is associated with your company name. Your company name has to be on the waybill for the cars and units you monitor. If you are not on the waybill, then you will not get any data returned by the service. If you have permission to monitor traffic for a company that is on the waybill, you can request that they add your company in the ZS monitoring role. See "What is the ZS role and how do I get it?"

The ZS role is a monitoring role. Shippers can authorize companies to be added to waybills in the ZS role so that they can use the BNSF Customer API to retrieve data regarding their shipments. There are a few different ways to get added in the ZS role. In the BNSF Customer portal, the shipper can issue a Letter of Authorization (LOA) for your company. It only takes a few minutes and will allow you to retrieve shipment data. To generate an LOA, log into the BNSF Customer Portal then click on My Apps then Letters of Authorization. Another way is to get your company added in the ZS role in the EDI request or AWI web application that creates the waybill.

The public version of DLL web app returns limited data for any unit you trace. The BNSF Customer API units service requires you to be on the waybill. See "What is the ZS monitoring role and how do I get it?" and "Why is no data returned for some of the cars or units I request?"

The Trial environment refers to the API gateway environment. We set you up there first so you can get your programs running. Trial is subject to outages from time to time while we perform maintenance and enhancements. Production has a much higher level of support and availability. Therefore, you should request a move to production as soon as you are ready.  You can do so by submitting a Message Us case requesting your certificate be moved to the Production environment.

The following roles are authorized to track shipments:

• SH: Shipper
• CN: Consignee
• BO: Beneficial Owner
• ZS: Monitor

Support information is displayed at the bottom of each of the BNSF Customer API pages.