Technical Integration Spec

Integration: [Source system] to [Target system] Prepared by: [Author / team] Date: [Date] Version: [e.g., 1.0] Status: [Draft / Approved]

---

1. Overview and systems

[One paragraph: what this integration does, why it exists, and the business outcome it enables. Name the source system (the system of record for the data) and the target system (where the data is sent), and state which side owns each part of the flow.]

System	Role	Owner	Environment(s)
[System A]	[Source of truth]	[Team / vendor]	[Staging, Production]
[System B]	[Downstream / consumer]	[Team / vendor]	[Staging, Production]

2. Integration flow

[Describe the flow in prose, step by step, so a reader understands the order of events without a diagram. For example: when a record is created in System A, it triggers a call to System B, which responds with an identifier that System A stores for future updates. State for each step whether it is synchronous or asynchronous, and if a webhook is used, describe which event fires it.]

3. Endpoints and operations

Operation	Direction	Sync / Async	Purpose	Request summary	Response summary
[Create contact]	[A to B]	[Sync]	[What it does]	[Key fields sent]	[Key fields returned]
[Update deal]	[A to B]	[Async]	[What it does]	[Key fields sent]	[Status / id returned]
[Status webhook]	[B to A]	[Async]	[What it notifies]	[Event payload]	[Acknowledgement]

4. Authentication

[State how the caller authenticates: the scheme (for example, an API key in a header, or a token obtained via a token exchange), where the credential is issued and stored, the scope it is granted, and how often it must be rotated. Note any IP allow-listing or signing requirements for webhooks.]

5. Data field mapping

Source field	Target field	Notes
[source.field_one]	[target.fieldOne]	[Type, format, or unit change; required or optional]
[source.field_two]	[target.fieldTwo]	[Default value if empty; trimming or casing rules]
[source.field_three]	[target.fieldThree]	[Lookup or transform applied; validation rule]

6. Error handling and retries

[Define how errors are classified and handled. State which responses are treated as transient (and so retried) versus permanent (and so surfaced). Describe the retry policy and where exhausted failures land.]

Condition	Classification	Action
[Timeout / 5xx]	[Transient]	[Retry with exponential back-off, up to N attempts]
[4xx validation]	[Permanent]	[Do not retry; log and alert; route to dead-letter queue]
[Rate limited]	[Transient]	[Back off per the rate-limit section, then retry]

7. Idempotency

[Describe how the integration prevents duplicate records when a call is retried. State the idempotency key (for example, a stable identifier from the source system), where it is sent, and how the receiver uses it to detect and ignore a repeat of an already-processed request.]

8. Rate limits

[State the published limit (for example, requests per minute), what the response looks like when the limit is hit, the back-off strategy the caller uses, and how large bulk operations are paced to stay under the limit.]

9. Security

[Cover transport encryption (for example, TLS for all calls), how secrets are stored and never logged, the least-privilege scope of the credential, how webhook payloads are verified (for example, a signature header), and how any personal data is protected in transit and at rest. Reference the relevant data privacy policy.]

10. Testing

[List the test cases that must pass before go-live, including failure cases. Name the test environment and any test accounts or sandbox endpoints.]

• [Happy path: a record created in the source appears correctly in the target]
• [Field mapping: each mapped field arrives with the right type and value, including empty-value rules]
• [Retry: a forced transient failure is retried and eventually succeeds without creating a duplicate]
• [Idempotency: the same request sent twice results in exactly one record]
• [Auth failure: an expired or wrong credential is rejected cleanly and alerts]
• [Rate limit: the integration backs off and recovers rather than failing the batch]

---

Open questions and assumptions

• [Any assumption about the other system's behaviour that still needs confirming.]
• [Any decision deferred to a later version.]