Custom integrations are a total headache. Here's why they're worth it.

If you’ve used Slack, Zapier, and other big SaaS platforms, you’ve run across the word integration.

You get that it means connecting something to those services. But when it comes to the app you’re building, the whole integration thing gets a lot murkier.

How does it actually work?

Are they all the same?

If you outsource an integration, do you need to hire a specific kind of developer later on?

These are really good questions that we get asked, so we decided to break them down.

Talk to me about app integrations

Integrations are how information gets from a database in one piece of software to another database in another piece of software. (What is a database?)

Imagine each database is a different shaped puzzle piece. To fit the two pieces together, you’d need a third piece—an integration—that’s designed to fit into the original two.                               

Integrations are how information gets from a database in one piece of software to another database in another piece of software.

In this way, an integration is a bit like a bridge; it connects and exchanges information between two places.

When you’re building an app, there’s a good chance you’ll integrate with something. These days, almost nothing is built without the help of several supporting services.

App integrations usually involve Application Program Interfaces, or APIs. (What is an API?) These provide defined ways to access, retrieve, and manipulate data from a piece of software. Companies explain their APIs in documentation—instructions on how code works and why certain pieces of code exist. Good documentation is kind of like a clear, detailed recipe; it shows developers how to produce a specific result, such as send a text message to the customer. Poor documentation leaves out important steps, gets key pieces of information wrong, or applies to outdated versions of the software. All of which means more time, guesswork, testing, and headaches for a developer.

Why use integrations?

Some integrations let you add useful features to your software, without having to build those features from scratch. For example, if you built a payment processing system from the ground up, it’d take loads of time and money—many months and thousands of dollars. But if you integrate with Stripe, you simply pay to use their service, and a developer can quickly connect to their software.

Other integrations let you connect your software to another software that your customers already use and love. (This is what we did for Case Status, explained below.) This helps you provide powerful customer benefits, such as efficiency or an “all-in-one” solution. It can also create a low entry bar, since customers don’t have to abandon or switch away from a piece of software they’re actively using.

If you’re outsourcing your software build, make sure you ask good questions and see how your partner approaches integrations and APIs.

What developers wish you knew about app integrations

When I asked Kevin Hoffman, one of our partners and Lead Developer, what he wished non-technical founders understood about integrations, he said he wished they understood the difference between an integration that you just plug-in and something that’s totally custom.

See, the biggest mistake non-technical founders make is assuming all integrations are equal. In reality, there are two main types: plug-it-in and custom.

Kevin says, “People will call them integrations, but the time it takes—from 5 minutes to a month—depends on what you’re actually asking for. Some of that stuff is copying and pasting a line of code, and then you have an integration. But if you have your own custom data and you’re trying to pull in other custom data then, yeah, it’s going to take time to massage it and make it all work.”

The difference between those two is significant. To revisit our bridge analogy, imagine laying a board across a creek bed vs. constructing a road bridge across a river. In terms of difficulty and time, that’s how much these two types can vary.

Plug-it-in integrations are quick and easy

These enable key features, but they don’t deal with heavy data transfers between your app and another piece of software. And since they’re fast and easy to maintain, you don’t need developers to keep them up and running.

Their main function is supportive and, for the most part, every developer integrates these in the same way. We may write a bit of custom code to make sure the tool plays nicely with your product, but the methods for adding any of these integrations are well established.                            

Stripe is the “gold standard” when it comes to documentation. Their detailed information makes basic Stripe integrations quick and painless.                                

Some examples of plug-it-in integrations are: Stripe for payment processing, Mailchimp for building an email list, and Segment for analytics. These are some basic tools we integrate into most apps we build. They take time, so you shouldn’t try and add a hundred of them, but they don’t take the weeks of effort that custom integrations require.

Custom integrations are intensive and time-consuming

Custom integrations handle transfers between two sets of custom data. For example, your app and another piece of software. This is what we did for the Case Status app (details below). Custom integrations can take one or more months to build because we're erecting a complex bridge from scratch.

They’re also intensive to maintain; as a founder, you do need developers to keep these up and running.

But don't let how hands-on they are intimidate you. Custom integrations have loads of benefits like marketing, moats, and boosting trust—we'll dive into all that later.

Gut check: do you need a custom integration?

Just like you want to ask yourself whether you need an app before you set out to build one, you want to ask yourself whether you need a custom integration before you commission one. Sometimes, there are ways to get around integrations. We’ve talked before about Wizard of Oz prototypes, where you make it look like work is being handled by software, when it's really being done by humans in the background.

It’s possible to have a Wizard of Oz solution with integrations, too.

For example, you could download a CSV from one software and upload it to your software, or vice-versa. You could even pay a Virtual Assistant (VA) or team member to manage this for your customers so it’s behind-the-scenes. You may also be able to use a service like Zapier, to easily connect a few services.                                

Usually, a customer doesn’t care how information gets from one place to another, so long as it gets there. And for some SaaS products, a behind-the-scenes solution is a better short-term option than a full custom integration, which is expensive and time-consuming. Make sure you ask your software partner whether this is a viable option.

Going behind the scenes of the Case Status <> Clio integration

We worked with non-technical founder Lauren Sturdivant to build Case Status, a client relationship and marketing portal for cutting-edge law firms. Case Status helps busy lawyers keep clients informed, spend less time on the phone, and boost firm revenue.                        

Building Case Status required building an integration with Clio, a separate piece of legal software. Many lawyers use Clio to manage their law firm's cases, intake, billing, and more. Without the integration, lawyers would have to copy and paste information between the softwares and very few busy lawyers (if any!) would use Case Status.

With the Case Status <> Clio integration, lawyers can display updates in Case Status, using data they’d already entered into Clio—with just a few clicks.                             

It takes very little customer effort to connect Case Status and Clio. But building that integration took weeks of focused effort.                                

This type of integration is the custom type; it’s not a plug-n-chug solution. To build the Case Status <> Clio integration, Kevin put in some serious work over an entire month.

The 5 stages of custom integrations

The time it takes to build a custom integration is divided into five buckets: research, architecture, building simple scenarios, managing complex scenarios, and maintenance. Each phase comes with its own set of challenges.

Step 1: Researching the other software

“With any sort of integration,” Kevin says, “the first step is to look at their documentation to kind of translate between your system and their system.”

For the Case Status <> Clio integration, this meant Kevin spent several days reviewing Clio’s available documentation. This helped him understand how Clio’s API works and what he’d have to do to connect to it.

One common issue for the research phase is this: the data looks different in your system when you compare it to the other system. When that happens, we have to translate the information to create a smooth flow from one system to the other. This is exactly what Kevin ran into when he researched Clio.

Case Status refers to cases as “cases,” while Clio refers to cases as “matters.” To make things even trickier, Clio’s documentation wasn’t always straightforward and often had limited examples. Kevin recounts, “Sometimes, it was hard to figure out what they were referring to or what they were talking about.”                                                        

‍

We typically have to cross our fingers and hope that a company’s documentation is up to date when we research a new integration. If the documentation is out-dated or incomplete, then we’ll need to figure out how the system works through trial and error (see Step 3). We’ll send some data to the API, and see what kind of response we get. Then we’ll tweak it and try it again.

Step 2: Architecture

Once Kevin had some general knowledge about Clio’s API, he started architecting the integration. He needed to figure out how to move data around and what structure could support that movement.

To revisit the bridge analogy, it’d be similar to figuring out whether a bridge is one-way or two-way; two lane or five lane; tall enough for a boat to pass under it; or accessible to all types of vehicles. Envisioning all the different scenarios he’d have to deal with was a lot to think through. But Kevin couldn’t skip this step—architecture determines how the integration works, and what its limits will be once it’s built.

Step 3: Building simple scenarios

“The first thing you do,” Kevin says, “is get it working with a simple scenario.” This means testing basic assumptions, like how you reach out to the other software’s API, retrieve data, and display it.

For the Case Status <> Clio integration, starting simple meant assuming that every client had just one case, and that all the information was properly filled out. Clients can, in the real world, have multiple cases, and this is something Kevin tested later under complex scenarios.

While the whole "starting simple" concept sounds straightforward, it’s something that can take upwards of 50 attempts to nail down in practice. Can you imagine trying a recipe 49 times before you have something edible?!

Although Kevin didn’t mention it, I imagine more than one object was tossed across the room during this phase.

Nerd Note: We practice test-driven development (what is TDD?), and testing most steps takes a while. It involves setting up a test account, manually adding a bunch of sample data, and then examining how well the integration handles moving, translating, and transforming that data. Not all integrations happen in real-time, which creates an additional testing hurdle.

Step 4: Addressing complex scenarios

Tens of attempts later, once Kevin nailed down the basics, he moved on to more complex scenarios. He also tackled what we call “edge cases,” which are uncommon situations. (It's a bit confusing, but the word "case" in "edge cases" here has nothing to do with lawyers or clients. It's a general term that's widely used in programming.) In Kevin’s words, “We first start with the best scenario, actually get it working, and then you start handling all the edge cases and ‘what if this is missing’ or ‘what if that is missing.’”

This is the part that Kevin is most proud of completing. It’s tricky, skilled work. It involves headaches and a great deal of perseverance, given how much time he already spent on simple scenarios. There are, after all, loads of different edge cases and figuring out how to handle them all is no joke.

Clever import reports

One really clever and useful piece Kevin developed during this period was an import report. It’s a detailed breakdown that shows lawyers which cases did, and didn’t import, from Clio and why. It’s incredibly handy and ensures there’s no guesswork around what information is where.

Authentication requests: the most frustrating piece

One of the hardest things about the Case Status <> Clio integration was working with Clio’s authentication system. Clio uses something called a token system to verify data requests. This is a good thing, because it prevents a random person from accessing the information in the software. But it did make the integration challenging.

What Kevin didn’t immediately recognize was there are two types of verification in Clio: “...you have an access token and a refresh token. Your access token expires every 2 or 3 weeks. So, if that expires, your client would have to go back in and manually re-authorize Clio.” Manual re-authorization is undesirable because it’d be a huge hassle and annoyance to clients. (Imagine your irritation when you unexpectedly have to re-login to iTunes and other apps you’re used to accessing!)

To prevent this, Kevin tracked the expiration date for tokens and set up a system that automatically refreshed it. That way, the client would never be troubled with this piece.

Thanks to Kevin, customers only have to authorize the integration one time, instead of every 2 weeks. They can essentially “set it and forget it.”                              

Getting it all to work seamlessly was challenging, and Kevin admits it was the most frustrating piece of the entire integration. But his effort was ultimately rewarding for the end product.

Automatic data refreshes

Another difficult piece was setting up data refreshes. While there’s a button that Case Status users can push to manually refresh everything, the software also auto-updates every evening to make sure everything is fresh the following day.

Step 5: Maintaining & improving the integration

While building the initial version of this integration took over a month of painstaking effort, it wasn’t the end of the road.

Case Status now has a CTO (our talented friend Andy Seavers), and a development team. We still join in on the weekly stand ups and provide ongoing support when needed.

As the product grows, it acquires new features and functionality, and those all affect the work Kevin has already done. He says you “have to keep in mind, ‘how does this affect the integration that we did?’”

Whenever you add new features and capabilities to your product, you may need to update your integration to account for these.

What else you should know about custom integrations

In addition to what goes into building an integration, there are a few other things you should know about them.

Your integration can be a marketing channel

Many apps have integration lists on their website. If you build a custom integration for an established piece of software, you may be able to make it on their integration list. This works best when you share a customer base with the other software, and can co-market. For example, Case Status gets a few sales leads from being in Clio’s integration list.                             

 Note that you won’t get this boost by plugging in Stripe or Segment—those tools are used by millions of other products. Listing your product wouldn’t benefit the other company at all.

Integrations may help you build a moat

Say a potential customer is comparing your software and another similar piece of software. If you integrate with tools the customer already uses, but your competitor doesn't, you could sway the customer toward your product. In this way, integrations provide a narrow moat; an advantage that helps you outperform competitors.

It's why established companies make their APIs public and build developer programs. These companies want other smaller companies to build integrations for them so the bigger companies can connect to as many tools as possible.

You can use integrations as trust tokens

Especially if your SaaS doesn’t have any name recognition, showing that you integrate with bigger brands, like Stripe or Salesforce, can increase your legitimacy in customers' eyes. When they see you work with tools they already use and trust, you increase the chances they’ll consider your tool as well.                              

How to hire developers when you have integrations

Custom integrations require a lot of maintenance and continual development. Eventually, you’ll want to hire a developer or CTO to maintain this internally.

When you do hire, you don’t need an “integrations expert” or engineer with a specific integration skillset to maintain what you've already built. Any skilled backend developer (what is the backend?) should be plenty familiar with integrations.

As we’ve mentioned before, we provide direction, an MLP build, startup advice, and support as our clients build up revenue. But at some point, we expect our clients to move away from our services and toward their own team.

You may be able to get customers to pay for integrations

Occasionally, you may be able to pass the cost for an integration to a customer. If a customer specifically requests an integration, they may be willing to pay a percentage of the cost to move that integration up your priority list.

Custom integrations are intensive, but don’t let that scare you

If you have a trusted partner and funds, there’s no reason to shy away from a custom integration. It can provide loads of customer value, and potentially supply other benefits like marketing and trust tokens.

True, they can be complex. But so is building a startup. And if you’re figuring out how to make that work, don’t let a technical integration intimidate you.