Step-by-Step Guide

Introduction

BNSF provides an Application Programming Interface for Customers (Customer API) to enable programmatic access to customer information. An API allows two application programs to communicate. By integrating the BNSF Customer API, you can integrate BNSF data into your enterprise systems.

These capabilities are provided as Representation State Transfer (REST) services. Information is returned in JavaScript Object Notation (JSON) name-value pairs.

Authentication

BNSF employs certificate based mutual (or two-way) authentication over HTTPS to allow each participant to validate the other party. Therefore, you will need a TLS (SSL) certificate from a trusted Certificate Authority in order to communicate with the BNSF Customer API. See the Onboarding section to learn how to register your certificate with BNSF's API Gateway.

For more information, please refer to the Mutual Authentication article in Wikipedia.

Onboarding

You will need to provide a BNSF.com User ID from your organization with access to the appropriate customer names.

Request a TLS/SSL Certificate from one of Wikipedia's Certificate Authority Providers list, except do not use Let's Encrypt. The certificate should be effective for a least one year and should include reasonable values for the following:

  • Country Name (2 letter code) [XX]:{Your Country Abbreviation}
  • State or Province Name (full name) []:{Your State}
  • Locality Name (eg, city) [Default City]:{Your City}
  • Organization Name (e.g, company) [Default Company Ltd]:{Your Company Name}
  • Organizational Unit Name (eg, section) []:{Your Technology Department}
  • Common Name (Important: the name of your company) []:{Company Name}
  • Email Address []:{Your tech email address}

Use the Registration form to submit your username and certificate to us.

Getting Started with Postman

Using Postman to test the API for the first time is really easy and an effective way for you to see how it works and how fast it is.

First, set up your client certificate by following Postman's instructions.

  • Host: api-trial.bnsf.com
  • Port: 6443

Use the Choose File buttons to set your CRT and KEY files. Passphrase is optional.

Once your client certificate is set up, create a new request in Postman as follows:

  1. Set method to POST
  2. Set the request URL to https://api-trial.bnsf.com:6443/v1/cars
  3. Add this header: Content-Type: application/json
  4. Set the body to raw JSON like this (replace the cars shown with your own cars):


    { "carList" : ["BNSF1111111","BNSF222222"] }

  5. You can change steps 2 and 4 to try other services. See Developer's Console

Troubleshooting Tips:

  • When trying to connect or download the certificate, make sure you are using port 6443
  • Make sure your certificates are in PEM format and unencrypted in Postman
  • Run a Health Check by requesting https://api-trial.bnsf.com:6443/healthcheck. You should get


    <status>OK</status>

  • Use Powershell's Test-Netconnection to verify you are not blocked by a firewall


    C:\> powershell Test-Netconnection -ComputerName "api-trial.bnsf.com" -Port 6443
    TcpTestSucceeded : True

You're all set!

API Support

Monday – Friday, 8 am – 5 pm (Central Time)
API Technical Support Email: CustomerAPI@bnsf.com