How the Flexport API enables global trade

Published in

GET PUT POST

8 min readFeb 22, 2017

Welcome to GET PUT POST, a newsletter all about APIs. Each edition features an interview with a startup about their API and ideas for developers to build on their platform.

This edition, I spoke with Sandy Spicer from Flexport. This company is tackling one of the oldest industries: international shipping. We dive into building a modern freight forwarder, how APIs are part of the strategy, and wrap up with some real-world shipping data.

Want the latest interviews in your inbox?

What is Flexport?

Flexport is an end-to-end freight forwarder. We manage imports and exports for clients that need to ship their products all over the world. Our biggest trade lanes are from China to ports on the West Coast (e.g. Long Beach, Oakland, and Vancouver).

We manage the entire process, from picking up goods at the manufacturer to dropping them off at distribution centers and warehouses. The journey includes about seven touch points with different companies.

Walk me through the shipping process.

The person picking up the goods may be a Chinese trucker transporting them to a local port. If a manufacturing plant isn’t by a large seaport, those goods will be put on a feeder vessel, which takes them to a larger port.

Different people own each port terminal and moving goods between them isn’t seamless. During that process, customs must be cleared. There are many variables we have to get right to follow all the laws and regulations.

When those goods get to the US, they might undergo exams from people other than customs officers. The FDA and other agencies inspect certain products, for example. Finally, we get those goods from the ports onto a train, and then they’re trucked to their destination.

Different companies handle each of these steps. Our job is to oversee the process and ensure that goods arrive at each point on the way. Unlike other companies, we provide a layer of customer service to our clients. Customer service is not a common strength of players in the freight forwarding business.

What are some companies that need a freight forwarding service?

Everyone who manufactures goods. With the exception of businesses like Apple, companies don’t run their own supply chains. Everybody who manufactures in China works with freight forwarders.

Why start with China?

The industry is based on trade lanes and a freight forwarder needs volume to get the best prices on a lane. It’s sensible to work on growing a small number of lanes in order to offer great prices. We started building our business by doing that with lucrative lanes in places like Shanghai.

As we’ve grown, we’ve been able to service more locations globally. We have shipments coming out of Southeast Asia, India, and even some from Europe. The majority still come from China.

We negotiate with the people who own those massive cargo ships. In the industry, pricing is done annually. Contracts set the amount of goods and the number of containers to be shipped monthly. Those details translate to rates with the owners of assets traveling on these lanes. Getting better rates requires shipping more and developing deeper relationships.

How is Flexport different and how do you use APIs?

We’re a software company doing freight forwarding. International shipping has been around for centuries. Even its modern form owes much to the Dutch in the 1600s and their activity between East Asia, India, and the Americas.

Much from that period persists. For example, the “Bill of Lading” — the classical way of releasing goods and proving ownership — requires three copies of a document and a process to state “Here are the documents. I have three of them. They’re from three different entities that were involved in this transaction, and that proves that I possess these goods.” This is an antiquated, paper-based process that stopped making sense when jet travel was invented.

What we’re trying to do at Flexport is bring everything online, including communication between touch points and stakeholders. They communicate via our app and website, not phone and email. Every step of the process is integrated into one supply chain with modern software like web apps and APIs instead of Excel, email, and antiquated EDI formats.

What are your thoughts on opening an API to developers?

Right now, the API is geared towards managing a supply chain for a business. That includes purchase orders, prices, quantities, and terms. We load that data into our app and use it to originate shipments.

When a supplier is ready, we can schedule the shipment. We know the quantities prescribed and where the manufacturer is in the process. It flows seamlessly. Our goal is to minimize the amount of human interaction necessary.

In what ways do your customers use the API?

Our clients also use our API to tie their shipment information into their dashboards and ensure that the data is accurate. They can track when goods will arrive at their warehouses and tell retailers when to expect re-stocks. The JSON API alerts them in real-time about delays.

Our API lets companies create shipments directly from their in-house software with minimal customization. They stay on their platform and communicate with us solely via the API. Compared to a lot of other developer platforms, ours lets you physically moves things.

How do you deal with accidental shipment requests?

We don’t dispatch goods until the supplier confirms that they’re ready. The supplier is integrated into our platform. When someone initiates a shipment, we check with suppliers to see if goods are ready. That way we can catch an accidental order.

How did the API get started?

Our first engineer, Andy built the initial API. He started with the essentials that powered our dashboard: quote requests and basic shipment status. Since then, we’ve built it out to support other aspects of our data pipeline.

Products can be updated and downloaded, network locations can be updated, and invoices can be accessed so clients can handle their entire billing system through the API. Additionally, they can create and get statuses for shipments underway.

What feedback have you gotten that’s made you decide to build new features into the API?

Our sales team helps us develop the right product for our customers. Businesses that aren’t ready to immediately ship are keen to come in, demo the software, and discuss the functionality they need for their supply chain. We talk with those customers, aggregate their feedback, and productize it.

Besides the people working on the API, how do you organize the engineering team?

Our core infrastructure team designs the data structures that support shipments on our backend. That directly ties into the API in terms of what data we need, what a shipment looks like, and how we model the process.

Clients often understand “shipment” in a variety of ways. Many think of a shipment as moving goods in a specific container. Others have a purchase order from one supplier traveling in multiple containers and think of that entire order as one shipment. Our infrastructure team tackles those problems.

We also have teams that work on product features. One team builds our marketplace and works with our pricing team to figure out how to aggregate the rates and quotes from different partners.

This makes it easy for our ops team to put quotes together, no matter what kind of shipment. They’re integral to the shipping process and respond directly to API requests in an internal dashboard. The first thing users want to know is how much a transaction costs and our ops team helps answer that.

Part of our work is to figure out how companies want to interface with us. Some companies are tech savvy and want to build on a modern API. Others want an FTP server with a nightly CSV file to share data.

Does Flexport get paid per shipment?

We set our own prices. When a freight forwarder books a shipment, it’s a mix of contracts negotiated with different partners. We figure in the costs of paying American and Chinese truckers plus ports’ holding fees. Part of the service is to aggregate that and issue a single invoice.

Dealing with the freight industry can be confusing and nasty. For example, some companies will add line items into an invoice like a “clean truck fee” or something equally unintelligible. They’re conning money out of inexperienced buyers.

Often, companies have little recourse because they’re not repeat players. We can better manage the partners because we are a repeat player and we only work with reputable companies.

How long do shipments take?

We give estimates because there are parts of the process we can’t control. Some government customs offices hold goods for over 30 days. They can open containers and inspect everything.

One time, customs opened up a box of our client’s goods (electronic devices) and they found that one minor component in these devices was counterfeit. They were installed illegally by a supplier and it took months to get resolved.

What technologies are in your stack?

Our API is simple. It’s all served through a Rails web app that takes requests, transforms them via form objects, and then updates our models in the database. We serve the web app all through Rails — just a different frontend that uses React instead of JSON.

An API needs to be exhaustively tested against different combinations of inputs. There have been instances when refactoring the data model inadvertently affected what would happen if a client hit our API with certain rarely used inputs.

It’s hard to deprecate an API, so if the data model changes we need to maintain a legacy API. It’s hard to future proof software and it’s important to ask “Does this encapsulate everything I want to do with this product in the future?” because we’ll need to support it for years.

Anything else you’d like to share?

We’d love to open up APIs and data sources for people to play with. Our CEO’s previous company, Import Genius, took publicly available data about imports and exports, added useful analysis, and sold that to customers.

As we continue building our data repertoire, we would love to anonymize confidential information and make it available to play with. As we grow, we look forward to providing resources like that.

Our data team has started on this with publicly available data. We have a handy data page where that team analyzes imports based on HS codes (customs classifications). You can look up any product and viewing where it’s shipping to and from.