What is API integration? A plain-English guide for people who sign off on systems

API integration, in one sentence#

An API (application programming interface) is a published set of rules that lets one piece of software ask another piece of software to do something or hand over some data. API integration is the work of connecting two or more systems through their APIs so that information moves between them automatically, in a format both sides understand.

Two words in that sentence matter most:

• Published. The vendor writes down what you’re allowed to ask for, how to ask, and what you’ll get back. That document is the API reference, and it’s the contract.
• Automatically. Once the connection is set up, a person no longer copies, pastes or exports a spreadsheet. The systems talk on their own, on a schedule or the moment something happens.

The bank-teller analogy#

Picture an old-fashioned bank. You can’t walk into the vault and take your money. Instead you go to the teller window, fill in a slip in the format the bank requires, show identification, and hand it over. The teller checks the slip, does the work behind the counter, and hands you back a receipt that says what happened.

An API is that teller window:

• The slip is the request, with fields filled in exactly as the bank expects.
• The identification is authentication, usually a key or token that proves who is asking.
• The teller’s rules (what you can ask for, how many slips per minute, which fields are required) are the API reference.
• The receipt is the response: either “done, here’s the result” or “rejected, and here’s why.”

The vault, meaning the vendor’s database and internal code, stays private. That’s the point. A vendor can rebuild everything behind the counter without breaking your integration, as long as the window keeps working the same way.

We’ll come back to the teller when we talk about what goes wrong, because almost every integration problem maps onto something that can go wrong at a bank window.

What actually travels between two systems#

Most business APIs today work over HTTP (Hypertext Transfer Protocol), the same request-and-response system your browser uses to load web pages. Mozilla’s developer documentation has a readable overview of how HTTP requests and responses work if you want the longer version. Each request has a few parts:

JSON (JavaScript Object Notation) is a plain-text format for structured data, defined at json.org. Despite the name, it is not tied to JavaScript; many programming languages read it. A response describing an order might look like this:

1
{
2
  "order_id": "10482",
3
  "status": "paid",
4
  "customer_email": "pat@example.com",
5
  "total": 149.00,
6
  "currency": "USD",
7
  "lines": [
8
    { "sku": "MUG-BLUE", "qty": 2, "price": 24.50 },
9
    { "sku": "TEE-L",    "qty": 1, "price": 100.00 }
10
  ]
11
}

You can read that without training. SKU stands for stock keeping unit, the product code your warehouse uses.

Many vendors describe their APIs in a standard machine-readable format called the OpenAPI Specification. The current version on the OpenAPI Initiative’s specification site is 3.2.1, dated 2026-09-10. When a vendor publishes an OpenAPI file, developers and integration tools can read the whole “teller rulebook” automatically, which tends to make connections faster to build.

You’ll also hear the term REST (Representational State Transfer), a common style for designing web APIs around resources like orders and customers. When a vendor says “we have a REST API,” they usually mean the endpoint-and-verb pattern in the table above.

The picture: one order, three systems#

Here’s the opening example drawn out. The online store is the source of truth for the order, and two other systems need to know about it.

1
 +----------------+      new order       +------------------+
2
 |  Online store  | -------------------> |  Accounting app  |
3
 |  (source)      |   POST /invoices     |  creates invoice |
4
 +----------------+                      +------------------+
5
         |                                        |
6
         | new order                              | "invoice 5531
7
         | POST /shipments                        |  created" (response)
8
         v                                        v
9
 +----------------+                      +------------------+
10
 | Warehouse app  | ---- tracking no. -> |  Online store    |
11
 | creates pick   |   PATCH /orders/10482|  shows "shipped" |
12
 | list, ships    |                      |  to customer     |
13
 +----------------+                      +------------------+

Three systems, four messages, zero retyping. Each arrow is one API request, and each one gets a response that says whether it worked.

Four ways systems get connected#

Not every integration is built the same way. These four patterns cover most of what a mid-sized business will run into.

The 45 in the first row isn’t a scare number; it’s arithmetic. With n systems, the maximum number of pairs is n × (n − 1) ÷ 2, and for ten systems that’s 45. A hub reduces it to ten connections, one per system. That’s the core argument for middleware software and for iPaaS (integration platform as a service), which is middleware sold as a hosted subscription. If you’re heading down that road, our rundown of iPaaS platforms compares the main vendors on pricing model and company-size fit.

Webhooks deserve a separate note. A normal API call is you walking up to the teller and asking. A webhook is the bank phoning you when a deposit clears. It’s the same family of technology pointed in the other direction, and most real integrations use both.

A worked example: connecting a CRM to an invoicing tool#

Let’s walk through a common request from a sales team: “When we mark a deal as won in the CRM, create the invoice automatically.” CRM stands for customer relationship management, the system where your sales team tracks leads and deals.

1. Find the trigger. In the CRM’s API reference, look for a webhook or event called something like “deal stage changed.” If it exists, the CRM can announce the moment a deal is won. If it doesn’t, you’ll need a scheduled job that asks the CRM every few minutes, “anything new?”
2. Decide what data travels. The invoice needs a customer name, billing address, line items, amounts, payment terms and a tax setting. List every field, and note which system owns each one.
3. Map the fields. The CRM might call it “Company” while the invoicing tool calls it “Customer name.” The CRM might store the amount as “149” and the invoicing tool might expect “149.00” with a separate currency code. Writing this mapping down is unglamorous, and it’s where most of the real work lives.
4. Handle the customer lookup. Does this customer already exist in the invoicing tool? If yes, attach the invoice to them. If not, create them first. Without this step you’ll end up with “Acme Inc”, “ACME, Inc.” and “Acme” as three separate customers.
5. Set up credentials. Each system issues a key or token to the integration. Many vendors use OAuth (Open Authorization), a standard that lets you grant one app limited access to another without handing over a password. The core standard is RFC 6749 at the Internet Engineering Task Force (IETF).
6. Plan for failure. What happens if the invoicing tool is down for ten minutes? A well-built integration retries, logs the error, and alerts a named person if retries run out.
7. Test with a fake deal. Mark a test deal as won, check the invoice, then delete both. Do it again with an existing customer, a deal in a different currency and a deal with no line items.

Nothing in that list requires deep technical knowledge to understand, and steps 2, 3, 4 and 6 are business decisions as much as technical ones. That’s why integrations go better when an ops lead sits in the room.

What goes wrong, using the teller#

Back to the bank window. Here are the common failure modes, each with its teller version.

Too many slips at once (rate limits). Banks don’t let one customer tie up the window all day. APIs cap how many requests you can make in a given period. Shopify, for example, describes enforcing most of its API limits with a “leaky bucket” model: each app gets a bucket of a set size, each request adds to it, and the bucket drains at a steady rate. When an API refuses a request for this reason, it typically answers with HTTP status 429, which MDN describes as “Too Many Requests”. Bulk imports and month-end jobs are where you’ll hit this.

The same slip handed over twice (duplicates). The network hiccups, the integration isn’t sure the first request landed, so it sends it again, and now the customer has two invoices. Good APIs offer a fix called idempotency: you attach a unique key to the request, and the server recognizes a repeat. Stripe’s API reference on idempotent requests explains how this works for payments, including that keys can be removed once they’re at least 24 hours old. Ask whether the systems you’re connecting support something similar.

The bank changes the slip (versioning). Vendors update their APIs. Fields get renamed, endpoints get retired. Responsible vendors publish version numbers and deprecation dates in advance. Integrations break quietly when nobody is watching those notices.

The ID card expires (authentication). Tokens expire, and keys get revoked when the person who created them leaves the company. A surprising number of “the integration just stopped” tickets come down to this. Create integration credentials under a service account the company owns, not an employee’s personal login.

The slip is filled in wrong (data mapping). A date written as 03/04/2026 means March in the US and April in much of the world. A blank field in one system might be required in another. These errors often don’t stop the integration; they just put wrong data in the other system, which is worse.

Nobody reads the receipts (monitoring). Every response says whether the request worked. If no one logs those responses or gets alerts on failures, problems surface weeks later in a customer complaint or an audit.

Build, buy or connect: who does the work#

There are three broad ways to get an integration in place, and the cost drivers differ.

A native connector is the cheapest route when it does what you need. Read its documentation closely, though: “integrates with” can mean anything from a full two-way sync to a one-time import. Custom code gives the most control and the most responsibility. Developers will sometimes use a vendor’s SDK (software development kit), a package of ready-made code for calling that vendor’s API; we explain the difference in API vs SDK.

Larger setups often put an API gateway in front of their own APIs to handle security checks, rate limits and logging in one place. A 20-person company rarely needs one, but you’ll hear the term from vendors and agencies.

Questions to ask a vendor before you sign#

Copy this list into your evaluation notes. A vendor that answers clearly in writing is usually a vendor whose API you can live with.

1. Do you publish a full API reference publicly, and is there an OpenAPI file?
2. Which plan tiers include API access? Are there per-call charges?
3. What are your rate limits, and what happens when we hit them?
4. Do you support webhooks for the events we care about (new order, payment received, record updated)?
5. How do you authenticate integrations? Can we use a service account rather than a person’s login?
6. How much notice do you give before changing or retiring an API version? Where are changes announced?
7. Do you support idempotency keys or another way to prevent duplicate records?
8. Is there a sandbox or test environment?
9. Which native connectors do you maintain yourselves, and which are built by third parties?
10. Can we export all of our data through the API if we leave?

Question 10 is the one people forget. An API is also your exit door.

What this means for a 20-person company

• Before buying any new system, check that it has a public API and that your plan tier includes it. This one check prevents most integration dead ends.
• Start with native connectors and an automation platform. Custom code makes sense when a workflow is core to how you make money and nothing off the shelf fits.
• Name one person who owns each integration and receives its error alerts. Unowned integrations fail silently.
• Keep a one-page map of which system owns which data (customers live in the CRM, invoices in accounting, stock in the warehouse app). Most sync disputes are really ownership disputes.
• Put integration credentials under a company-owned account, and review them when someone leaves.

The one idea to keep#

If you remember one thing, make it the teller window. Your systems don’t need to know how each other work inside. They need a clear, stable window, a valid ID, slips filled in correctly, and someone who reads the receipts.