Technical Integration Spec

What a technical integration spec is

A technical integration spec is the document that defines exactly how two software systems will talk to each other. It names the systems involved, the operations they call, how those calls are authenticated, which fields map to which, what happens when something fails, and how the integration will be tested before it goes live. It is the shared contract that lets two teams build to the same expectations without constantly interrupting each other to ask "what does this field mean again?".

A good integration spec does three jobs at once: it removes ambiguity about the interface, it makes failure behaviour explicit before it bites you in production, and it gives both sides a single source of truth they can review, version, and sign off on.

What it covers

An integration spec is broader than a single endpoint description. It should cover:

• Systems and ownership — which system is the source of truth, which is downstream, and who owns each.
• Endpoints and operations — the calls each system exposes, what they do, and the shape of their request and response payloads.
• Authentication — how the caller proves who it is and how credentials are issued, stored, and rotated.
• Data mapping — how a field in one system corresponds to a field in the other, including type changes, unit conversions, default values, and the rules for when a value is missing.
• Error handling — how errors are detected, classified, retried, and surfaced to a human when retries are exhausted.
• Rate limits — how many requests are allowed in a window and how the integration backs off when it is throttled.
• Idempotency — how the integration avoids creating duplicate records when a call is retried.
• Security — transport encryption, secret handling, the least-privilege scope of credentials, and how personal data is protected in transit and at rest.

If your spec only documents the happy path, it is not finished. Most integration pain lives in retries, duplicates, and partial failures.

Sync versus async and webhooks, in plain terms

There are two broad ways for systems to exchange data, and the spec must say which one is used for each operation.

Synchronous (sync) means the caller sends a request and waits for the answer before doing anything else, like asking a question and standing there until you get a reply. It is simple and gives an immediate result, but it ties up the caller while it waits and it fails awkwardly if the other system is slow.

Asynchronous (async) means the caller hands off the work and carries on, and the result arrives later. A common async pattern is the webhook: instead of the caller repeatedly polling and asking "is it done yet?", the other system pushes an event to a URL you registered the moment something happens, like getting a text message when your order ships rather than checking the tracking page every hour.

Sync is best when the caller genuinely needs the answer right now and the work is fast. Async and webhooks are best for events that happen on the other system's schedule, for slow work, and for keeping two systems in step without constant polling. A spec should state, per operation, whether it is sync or async, and for webhooks it must define the event types, the payload, and how the receiver acknowledges and secures them.

Who uses it

Integration specs are written and read by the engineers building each side, the QA testers who verify the behaviour, and the technical leads who sign off on the design. Product and project managers use it to understand scope and dependencies. When a vendor or partner is involved, the spec is the artefact both organisations agree to before any code is written, which is why clarity matters more than polish.

How it relates to other technical documents

An integration spec sits alongside the broader technical specification and depends on the shared understanding captured in the data model and the system architecture. On a client engagement it is often a deliverable named in a software development proposal. Keep these documents cross-referenced rather than copying content between them.

Common mistakes to avoid

• Documenting only the happy path. Specify what happens on timeout, on a 4xx, on a 5xx, and on a duplicate before they happen in production.
• No idempotency story. If a retried call can create a second record, you will get duplicates. Define an idempotency key and say how the receiver uses it.
• Vague field mapping. "Sync the contact" loses; a row-by-row table of source field, target field, and the rule for each wins, including what to do when a value is empty.
• Ignoring rate limits until you hit them. State the limit and the back-off strategy up front.
• Hard-coding or emailing secrets. Say where credentials live, how they rotate, and the least-privilege scope they carry.
• No versioning plan. When the interface changes, callers must not break silently. Define how versions are signalled and how long old ones are supported.
• Skipping the test plan. An untested integration is a guess. List the cases, including failure cases, that must pass before go-live.