Skip to main content
SaaS Directory Info

Reference edition 2026.47

Sign in

Documenting SaaS Integrations So Buyers Can Check Them

Reference · 9 min read ·

How to describe native, API-based and webhook integrations accurately: what to list, how to label direction and depth, and how to keep the table true.

Illustration: A handbook-style integration matrix: product names down the left, columns for type, direction and depth, muted teal checkmarks and dashes

Ask a buyer what they check before they commit to a new tool and integrations come near the top. Their existing stack is a given; the new product has to connect to it. Yet integration pages are among the vaguest on any software site. A grid of logos tells the reader that a connection exists and nothing about what it does, who built it, how deep it goes or whether it works in both directions.

This guide sets out how to document integrations so that a buyer can check each claim, and so that a reviewer or an assistant that quotes you does not have to guess. It is a how-to: by the end you should be able to turn a logo wall into a table that tells the truth.

Why logos are not enough

A logo says "we have something to do with this company". It does not say whether the something is a deep, supported, bidirectional connection or a one-time CSV export that a customer once managed to upload. Two products can show the same logo and offer completely different value.

The consequences are practical. A buyer who assumes a deep connection and finds a shallow one feels misled and tells others. A support team receives questions it cannot answer from the documentation. A comparison site that copies your logo list repeats the overstatement.

The fix is to describe four properties for every integration: type, direction, depth and status.

Property one: type

Types differ in who maintains the connection and what the customer must do.

  • Native. The vendor built and supports it. The customer enables it in settings, signs in to the other service and chooses what to sync.
  • Public interface. The vendor offers an application programming interface and the customer, a consultant or the other party builds the connection. The interface is documented but the connection is not packaged.
  • Webhook. The product sends an event to an address the customer chooses when something happens. It is a building block rather than a finished feature.
  • Third-party relay. An automation or integration platform links the two products. The platform may charge separately and has its own limits.
  • File exchange. Import and export through files. Useful, honest and worth listing, but not the same as a live connection.
  • Agent or tool protocol. Some products now expose tools to AI assistants through the Model Context Protocol, an open standard for connecting assistants to data sources and tools. If you offer a server of this kind, list it as its own type and link to its setup page.

An application programming interface, in general terms, is a defined way for one piece of software to ask another to do something. Calling an interface an "integration" without saying who builds the other half is a frequent source of confusion.

Property two: direction

State which way the data travels.

  • Inbound: data comes into your product from the other service.
  • Outbound: data leaves your product for the other service.
  • Two-way: both, with a stated rule for conflicts.

For two-way connections, say what happens when the same record is changed in both places. Last write wins? The newer timestamp? A flagged conflict for a human? Buyers who rely on the connection for accuracy need this, and it is a fact only you can supply.

Property three: depth

Depth is what the connection actually moves. Write it as a short list of objects and operations.

  • Contacts: create, update, delete, read.
  • Invoices: read only.
  • Attachments: not supported.

A simple three-level scale also helps: basic (identifiers and a few fields), standard (the common objects and fields) and full (every object the other service exposes to integrators). Define your scale once on the page and use it consistently. If you cannot define the scale honestly, list the objects instead.

Property four: status

Each row needs a status and a date.

  • Available: supported and tested against the current version of the other service.
  • Beta: works, but may change and has limited support.
  • Deprecated: still working, scheduled for removal, with a date and a replacement.
  • Planned: listed only in a roadmap section.

Add the date you last verified the connection against the other service, and the version of that service if it publishes one. Connections break when either side changes. A "verified on" date is the quickest way to show that someone is paying attention.

Building the table

Put the four properties in a real table, not an image. A good row reads:

Service Type Direction Depth Status Verified Setup
Calendar service Native Two-way Events: create, update, delete Available Month and year Link

Keep the first column alphabetical so a reader can scan it. Group by category only if the list is long. Put the setup link in every row, because an integration with no instructions is an integration that generates tickets.

Where you offer several connection types to the same service, give each its own row. "Spreadsheet service, native, inbound" and "Spreadsheet service, relay, two-way" are different offers and a buyer may want one but not the other.

What to say about limits

Every integration has limits. Write them down.

  • Rate limits: how many calls per minute or day the connection may use.
  • Volume limits: the maximum number of records per sync.
  • Plan limits: whether the connection is available on every plan.
  • Latency: whether sync is immediate, scheduled or manual.

A buyer who plans to move a large archive needs to know that before signing up. A limit that is published is a design constraint; a limit discovered after purchase is a grievance.

Do not forget the reverse direction

Integrations are two-sided. If another company builds a connection to your product, say so, and link to their page, but mark it as third-party and say who supports it. Buyers should know whom to ask when something breaks.

If you are a small product that connects to a larger one, check the larger one's own listing rules before you use its name or logo. Many platforms publish brand guidelines, and following them keeps the relationship friendly.

Keeping the table honest over time

An integration table decays faster than most pages because it depends on two moving products. A few habits keep it accurate.

  1. Assign an owner. One person reviews the table on a schedule.
  2. Test on a schedule. Run each integration end to end, or have an automated check that proves the connection works.
  3. Link to the changelog. When you change an integration, record it publicly.
  4. Retire gracefully. If you drop a connection, mark it deprecated for a stated period, then remove it and say why.
  5. Avoid counting. "Over a hundred integrations" is hard to verify and tempts you to count shallow ones. List what exists and let the reader count.

Using a directory listing to support the table

If your product is listed on a software directory, use the listing's fields consistently with your own table. The listing should name the main integrations in the same words. When a buyer reads the directory entry and then your page, they should find the same facts. Use the search and categories pages to see how comparable products describe the same connections, then match the level of detail rather than inflating yours. The developers page describes the free interface and tool server that let others read listing data programmatically, which is useful if your integration list feeds into a catalogue elsewhere.

A short checklist

  • Every row has type, direction, depth, status and a verified date.
  • Planned items live in a separate section.
  • Third-party connections are labelled and attributed.
  • Limits are stated next to the row they apply to.
  • Setup links work.
  • The table is text, not an image.
  • Someone owns the review.

Two short case studies

A small project tool with a deep connection. The team behind a project tracker offers a native connection to a code hosting service. Their first table said only "Code hosting: yes". After a review they rewrote the row: native, two-way for issues and comments, read-only for pull request status, no support for private forks, verified against the host's current interface in the previous month, with a link to the setup guide. Support questions about the connection fell, because customers could see the boundaries before they started, and the product page became the thing partners linked to when explaining what worked.

A reporting product that relies on a relay. A reporting tool has no native connectors but works well through an automation service. Instead of listing dozens of logos, the team listed the automation service once, documented the triggers and actions it exposes, stated that the service has its own plans and limits, and gave three worked examples. The page was shorter than a logo wall and more useful, and it avoided implying a native connection that did not exist.

Both examples have the same lesson: precision costs a few lines and saves a great many conversations.

Writing the introduction to the table

Place two or three plain sentences above the table. Say what the types mean in your own product, how you define depth, and when the table was last reviewed in full. Readers use this paragraph to calibrate how much to trust the rows beneath it. Avoid promotional claims here; the introduction is part of the evidence.

Summary

Integration pages work when each row carries four facts: type, direction, depth and status, with a date. Separate native connections from interfaces, webhooks and relays; separate available from planned; write limits beside the row they limit. Test on a schedule and retire connections openly. The reader who sees a table like this learns what they need in a minute, and the assistants and comparison sites that copy it will repeat something true.

Questions and answers

What counts as a native integration?
One that the vendor builds and maintains, that a customer can switch on from within the product without writing code. Anything that needs a custom script or a third-party relay is a different type and should be labelled as such.
Should I list integrations that are only planned?
Only in a separate, clearly labelled roadmap section. Mixing planned and available integrations in one table is the commonest way to mislead a buyer.
What is the difference between one-way and two-way sync?
One-way sync copies data from a source to a target and never writes back. Two-way sync propagates changes in both directions and needs rules for conflicts.
How should I describe an integration through an automation service?
Name the service, say that it is a third-party connection, list the triggers and actions available and note whether the automation service charges separately.

Sources

Related guides

Questions?