Back to Templates
ICRIntegrationInterface ContractAPI

Integration Contract Record (ICR) Template

A Markdown template for the agreement behind one integration between systems: purpose and parties, the pattern and its interaction flows, the interface specifications it relies on, data, security, service levels, error handling, change and support, and testable acceptance criteria. Written so a reviewer, an operator or an AI coding agent can act on it. Version 0.2 of the format, a draft.

Build it interactively in the ICR Builder (opens in a new tab)

A draft format, version 0.2. It is in the spirit of MADR: a short Markdown document with a fixed structure that can be reviewed in a pull request. It does not replace OpenAPI, AsyncAPI or the Open Data Contract Standard. It records the agreement around the interface those describe, and links to them. No standards body has reviewed or endorsed it.

The template and its schema, and the whole Appointment Booking sample (a design, seven decisions, requirements and three contracts), are in the public architecture-records repository. The template and its schema are licensed under CC BY 4.0, like the other templates there: you may copy and adapt them, including commercially, if you give credit to IT Architecture Patterns and say what you changed.

Last Updated: October 14, 2026

Copy and download act on the blank template shown below.

The example is the contract between the booking widget and the Booking API in Appointment Booking (sample), a fictional system documented with the templates on this site. Its other two contracts, one for calendar synchronisation and one for notifications, are in the same project. See the contract on GitHub (opens in a new tab)

See all the records of the Appointment Booking worked example together

icr: "0.2"
id: "{ICR-XXXX}"
title: "{short name of the integration}"
status: "{draft | proposed | agreed | active | deprecated | retired}"
version: "{0.1.0}"
date: "{YYYY-MM-DD}"
pattern:
  id: "{pattern id, e.g. int-api-external}"
  url: "{link to the pattern}"
interaction: "{sync-request-response | async-event | async-message | stream | batch-file}"
provider:
  system: "{system offering the interface}"
  owner: "{accountable team}"
  contact: "{email or channel}"
consumers:
  - system: "{consuming system}"
    owner: "{accountable team}"
    contact: "{email or channel}"
interfaces:
  - type: "{openapi | asyncapi | odcs | cloudevents | wsdl | json-schema | other}"
    ref: "{path or URL to the authoritative specification}"
    version: "{interface version}"
data:
  classification: "{your organisation's classification}"
  personal-information: {true | false}
decisions: []

{integration title}

Purpose

{The capability this integration serves, who depends on it, and what happens to them when it stops.}

Parties and responsibilities

PartySystemResponsible for
Provider{provider system}{what this party builds, operates, monitors and changes}
Consumer{consumer system}{what this party builds, operates, monitors and changes}

Interaction

  • Pattern: {pattern name}, {any deliberate deviation from it, and why}
  • Direction and trigger: {who starts an exchange, and what starts it: a user action, an event, a schedule}
  • Volume: typical {n per unit}, peak {n per unit}
  • Ordering: {whether order matters, and what guarantees it}

Interaction flows

{The main exchange, and the failure the parties must handle, in one sentence.}

sequenceDiagram
  accTitle: {The main exchange}
  accDescr: {Two or three sentences: who calls whom, what comes back, and what happens when a part fails.}

  participant C as {Consumer name}
  participant P as {Provider name}

  C->>P: {request message}
  alt normal path
    P-->>C: {response message}
  else a part fails
    P-->>C: {what the consumer is told}
  end
  1. {Step, naming the party and the message}
  2. {Next step, including how the failure is handled}

Interface specification

  • {specification type} {specification reference} {interface version}: {what it covers}; authoritative copy: {where the authoritative copy lives}
  • Design standard followed: {for example a national or organisational API design standard, or "none"}

Examples

The main exchange:

{The request and its response, the event with its envelope, or the file excerpt}

The main error, as the consumer receives it:

{The error}

Environments and onboarding

Optional — remove this section if you don't need it.

  • Environments: {test and production: where each is, and how they differ}
  • Test data or sandbox: {what exists, and what it does not simulate}
  • Access: {how a new consumer asks, who approves, how long it takes}
  • First call: {the smallest exchange that shows a new consumer is connected}

Data

  • Entities: {the business entities that cross the interface}
  • Classification: {data classification}; driven by: {which fields}
  • Personal information: {none, or which fields, and the basis for sharing them}
  • Residency: {where the data may be stored and processed}
  • Retention: provider {provider retention period}; consumer {consumer retention period}
  • Data quality: {the rules the data must meet (completeness, validity, uniqueness), and who is told when they are broken}

Security

  • Authentication: {how each party proves who it is, for example OAuth 2.0 client credentials or mutual TLS}
  • Credential issue and rotation: {who issues credentials, and how often they change}
  • Authorisation: {what each consumer may and may not do}
  • Transport: {protocol and minimum TLS version}
  • Network path: {public internet, private link or dedicated connection, and any allow-listing}
  • Pattern controls inherited: {the pattern}; additional controls: {what this integration adds}

Service levels

  • Availability: {availability target}, measured at {measurement point}
  • Latency: {percentile and limit}, measured at {measurement point}
  • Throughput: {throughput limit}, beyond it: {behaviour beyond the limit}
  • Freshness: {how soon a change at the source is visible to consumers}
  • How a consumer learns its limit and its use of it: {response headers or documentation}
  • Recovery: time {how long the integration may be down}; point {how much it may lose}
  • Support hours for these objectives: {support hours}

Error handling

  • Errors and their meaning: {each error the provider returns or emits, and what it means to the consumer}
  • Timeouts: {on each side}
  • Retries: {who retries, how many times, with what backoff}
  • Idempotency: {how a duplicate is recognised and made harmless}
  • Failed messages or files: {where they go (dead-letter, quarantine) and who is alerted}
  • Recovery after an outage: {how a consumer catches up: replay, resend window}

Change and versioning

  • Interface versioning: {the scheme, for example a major version in the path}
  • Breaking change means: {what counts as one}
  • Notice before a breaking change or deprecation: {notice period}, via {notice channel}
  • What each consumer relies on: {fields, behaviours and timings, or a link to its contract tests}
  • Changing this ICR: {who approves}

Observability

  • Correlation identifier: {the identifier, and how it propagates}
  • Logs: {what each side logs, without logging classified payloads unnecessarily}
  • Metrics and alerts: {metric, threshold, recipient}

Support and escalation

PartyContactHoursEscalation
{party name}{email or channel}{support hours}{who is next}

Severity levels and response targets: {each level, what it means and the response target}

Acceptance criteria

  1. {A testable statement} — proved by: {the test, synthetic check or alert}
  2. {Another testable statement} — proved by: {the test, synthetic check or alert}

Related records

Optional — remove this section if you don't need it.

  • Pattern: {the pattern page}
  • Decisions: {the decision records this contract rests on}

Open issues

Optional — remove this section if you don't need it.

  • {The question}: {owner of the question}, {date raised}