Trace — A workflow and data movement map.
Map current hand-offs and authoritative records.
Capability record · Reviewed 2026-09-03
API and systems integration
Connect applications, suppliers and operational systems through bounded, validated and observable interfaces.
01
Fit
When this capability belongs in the delivery path.
- 01
A product must use an existing system of record or third-party API.
- 02
A manual hand-off, duplicate entry or unreliable synchronisation is blocking work.
- 03
An AI-enabled workflow needs controlled access to tools or operational data.
02
Typical work
The work is shaped around a bounded operational outcome.
- 01
API contracts, events, validation, idempotency and error handling.
- 02
Identity, permission, data classification and service-boundary design.
- 03
Integration observability, fallback, migration and release planning.
03
Workflow
A delivery sequence with an output at every gate.
Contract — An interface specification.
Define narrow operations and validation.
Prove — Acceptance and recovery evidence.
Test normal, partial-failure and duplicate paths.
Run — Owned operational signals.
Monitor dependency health and exceptions.
04
Technical decisions
Evidence and boundaries stay beside the decision.
Which system owns the record?
Data model and business process map. Boundary: A sync or AI summary is not a new source of truth.
What may call the API?
Service identity, scopes, validation and audit requirements. Boundary: A model cannot grant itself permission.
How does failure behave?
Retry, duplicate, fallback and escalation design. Boundary: An API success path does not cover distributed failures.
05
Practitioner notes
What this capability means in the work itself.
Map authority before moving data
An integration design should begin by asking which application is authoritative for each field and business event. Without this, teams often create a second record that is almost, but not quite, the same as the original. Disputes then appear as data-quality problems even though they are ownership problems. The map should also show when information becomes valid, who may amend it, which downstream systems consume it and how corrections travel. This is especially important for AI-enabled workflows, where a generated summary or recommendation can be valuable but must not silently become the authoritative customer, case or financial record.
Prefer narrow, explicit contracts
A dependable interface exposes the smallest useful operation: retrieve an approved case summary, create a draft task with validation, or submit a status update with a clear schema. Broad access to an entire database or an unbounded ‘do anything’ endpoint is difficult to review and difficult to operate. Contracts should state required fields, validation expectations, response semantics, versioning assumptions and who owns a breaking change. A narrow contract may feel slower at first, but it provides a practical security and quality boundary and makes later supplier or product changes less disruptive.
Engineer for ordinary failure
Distributed systems fail in partial and confusing ways. A calling service may time out after the receiving service has already completed the action; a retry may create a duplicate; a queued event may arrive late; an upstream record may be deleted or amended. Integration work should make these behaviours visible through idempotency choices, timeouts, retries, dead-letter or exception handling where appropriate, and a human route to investigate. The aim is not a promise of perfect synchronisation. It is a known response when dependencies are slow, unavailable or inconsistent.
Use service identities and constrained permissions
Integration credentials should represent a service or workload with the least practical access, rather than an employee account copied into configuration. The design should account for how credentials are stored, rotated and disabled, what scopes are granted, and how actions are attributed. For AI workflows, tool access needs an additional check: the model’s natural-language output is not itself an authorisation decision. The application should validate inputs, enforce allowed operations and preserve a confirmation or escalation route where the action has meaningful impact.
Make supportability a design outcome
When an operational user reports that a record did not update, support needs to determine what happened without guessing. Proportionate correlation identifiers, status records and error context can connect the visible workflow to the involved services while respecting data-minimisation and retention decisions. The system should also state what users can do while a dependency is unavailable: wait, save a draft, use a controlled manual process or raise an exception. These choices belong in acceptance testing because a successful integration demo does not prove that the hand-off remains workable under pressure.
Plan change as a shared responsibility
An interface contract is an agreement between teams, not a one-time technical export. The delivery plan should identify who announces a breaking change, how consumers discover a new version, whether old behaviour is supported for a limited period, and how a failed rollout is reversed. Where a third-party API is involved, the product must accommodate published limits and change processes rather than assuming control over them. These details are especially valuable in urgent work, because a rapid first connection can create a durable dependency. Recording the boundary early gives the organisation a route to evolve the integration without silently disrupting the operational work built around it.
Reconcile outcomes, not just requests
For important operations, the team should decide how it knows that the intended business outcome occurred. A client request may receive a success response while a downstream process later rejects, delays or amends the work. Status design should therefore distinguish request receipt, accepted processing, completed outcome and known failure where the workflow requires it. Reconciliation can be automated, reviewed through an exception queue or performed at an agreed interval, depending on the volume and impact. The point is to avoid equating network success with operational completion, particularly when an integration crosses suppliers, queues or multiple systems of record.
06
Acceptance
Evidence expected before the next release decision.
- 01
Representative requests succeed and invalid requests fail safely.
- 02
Permissions, duplicates, timeouts and partial writes are tested.
- 03
Owners can locate an interaction through proportionate correlation records.
07
Dependencies
Inputs and owners the capability cannot manufacture alone.
- 01
Provider/API documentation and a named technical owner.
- 02
Authorised sandbox or controlled test access where available.
- 03
Clear data, security and release responsibilities.
08
Risks and limits
Where a careful answer stays conditional.
- 01
Supplier changes, limits and outages remain external dependencies.
- 02
Regional or privacy assertions depend on the complete selected data path.
- 03
An integration cannot compensate for a disputed process or data owner.
Direct answers
Questions about api and systems integration
01Can an agent call operational systems?
Only through deliberately limited, validated operations with suitable permissions and confirmation routes.
02Does an API integration guarantee real-time accuracy?
No. Timeliness, retry, data-quality and error behaviour are properties to define and test.
Source discipline
Primary guidance and technical references
A practical next step
Use this capability inside a real delivery decision.
Share the workflow, existing systems, constraints, risk and evidence you need from the first useful release.
Discuss the work