How to Write an Integration Design Document in English
Learn the structure and vocabulary for writing professional integration design documents in English, including data flow, field mapping, and error handling.
What Is an Integration Design Document?
An Integration Design Document (IDD) is a technical specification that describes how two or more systems exchange data. If you work with APIs, third-party platforms, or enterprise software, you will almost certainly need to write or review one. Knowing the correct English vocabulary and structure makes this process far smoother — both for you and your readers.
Standard Structure of an IDD
1. Overview and Purpose
Begin with a short paragraph that answers three questions: What systems are being integrated? Why is this integration needed? Who will use the exchanged data?
Example phrase: “This document describes the bi-directional integration between the CRM platform and the billing service, enabling real-time synchronisation of customer account status.”
2. Data Flow Diagram
Include a diagram and a written description of the data flow. Use directional language clearly:
- “Data flows from the source system to the target system.”
- “The event is triggered by a change in the order status.”
- “The payload is forwarded to the downstream consumer.”
3. Field Mapping
A field mapping table matches source fields to destination fields. Describe any transformations applied during transit.
| Source Field | Target Field | Transformation |
|---|---|---|
customer_id | account_ref | Direct mapping |
created_at | registration_date | ISO 8601 → Unix timestamp |
4. Error Handling
Describe what happens when something goes wrong. Cover retry logic, dead-letter queues, and alerting.
Example phrase: “If the target endpoint returns a 5xx response, the integration will retry up to three times with exponential back-off before routing the message to the dead-letter queue.”
5. Security Considerations
Document authentication methods, data encryption, and access controls.
Example phrase: “All API calls are authenticated via OAuth 2.0 client credentials flow. Sensitive fields are masked before logging.”
Key Vocabulary
Idempotency — the property of an operation that produces the same result whether it is performed once or multiple times. Use this when discussing safe retries.
Transformation — the process of converting data from one format or structure to another during transit.
Mediation — the role of a middleware layer that sits between two systems and handles routing, transformation, and protocol conversion.
Payload — the body of a message or request containing the actual data being transmitted.
Orchestration — coordinating the sequence of calls across multiple services to complete a workflow.
Schema — the formal definition of the structure, field names, and data types in a message or database.
Five Example Sentences
- “The integration design document specifies that all outbound requests must include an idempotency key to prevent duplicate order creation.”
- “During the data transformation step, the date format is converted from MM/DD/YYYY to ISO 8601 before being written to the target table.”
- “The mediation layer handles protocol conversion between the legacy SOAP service and the modern REST API.”
- “Field mapping must account for nullable fields on the source side that are mandatory in the target schema.”
- “Error handling logic routes any malformed payloads to the dead-letter queue and triggers an alert to the on-call engineer.”
Writing Tips
Keep your IDD concise but complete. Use tables and numbered lists rather than long prose paragraphs. Always version your document — include a revision history table at the top. Write in the present tense for how the system behaves (“the service sends”) and the future tense for what will be built (“the adapter will validate”).
Avoid vague verbs like “handle” or “process” without qualification. Say specifically how something is processed — is it validated, transformed, stored, or forwarded?