Direct answer
An integration specification is the data contract between two systems: what moves, in which direction, when, in what shape, and what happens when something goes wrong. Writing it before anyone connects anything turns a vague wish ('sync the CRM with accounting') into something that can be reviewed, priced and tested. It does not need to be technical. Most of it is business decisions such as which system wins when two values disagree. The eight sections below can be filled in a table or a short document, one integration at a time. Connections are scoped per project through API or webhook after a technical review of each system; this template does not assume that any tool has a ready-made connector. To pick which system is authoritative, read system of record for integrations first.
1. Systems and owners
Name each system in the integration, the person or team who owns it, and the person who can grant technical access. Note which plan or edition each runs on, since some interfaces are limited by plan and this is worth confirming early. Record who is the business owner for the data that moves, because that person decides disputes about it.
2. Direction and trigger
For each flow, state the direction (system A to B, B to A, or both) and what starts it. Common triggers:
- A record is created or reaches a particular status
- A form or message arrives
- A schedule fires at a set time
- A person presses a button or approves something
- A change is made in the other system
3. Field map
The field map is the heart of the document. Make a table with one row per field and columns for source field, target field, format, required or optional, and any transformation. Note differences such as dates, currencies, units, names split into parts and values that come from a fixed list in one system and free text in another. For each list, map every allowed value to its counterpart. Mark fields that are read-only in the target, since writes to them will fail.
4. Frequency and volume
Decide how quickly a change must appear on the other side: immediately, in batches or on a schedule. Estimate volumes in your own terms, such as records on a busy day and how many are updated more than once, and mark them as estimates. Volume matters because every system limits how many requests it accepts, and the design has to stay inside those limits. Note whether an initial load of existing data is needed in addition to ongoing changes.
5. Identifiers and duplicates
Decide how a record in one system is matched with its counterpart. A shared identifier stored in both systems is far safer than matching on names. Write down what happens when no match is found, when several matches are found and when a record is deleted or merged on one side. Decide which system wins when the same field differs. Without these rules, duplicates and overwritten values are the usual result.
6. Errors and retries
Every integration fails sometimes: a system is unavailable, a field is invalid, a permission is missing. Specify what should happen in each case:
- Which failures are retried automatically, and which need a person
- Where failed items are held so nothing is lost silently
- Who is told, through which channel, and how quickly
- How a corrected item is resubmitted without creating a duplicate
- What is logged, and who may view it
7. Authentication
Record how each system will accept the connection: a dedicated service account, an API key, or another method the system supports. Prefer an account created for the integration, in your name, with only the permissions the flow needs, over a personal login. State who holds the credentials, where they are stored and how they are rotated or revoked. Never put credentials in the specification itself. The API credentials and service account setup page explains the preparation.
8. Test cases
Write the tests as part of the specification, using real examples. Cover a normal record, a record with missing optional data, a record with invalid data, a duplicate, an update after creation, a deletion, and a case where the target system is unavailable. For each, state the expected result. Agree who runs the tests and who signs them off. Test in a non-production environment where the systems provide one, and say so where they do not.
Where LATYNEX fits
If you want help writing or delivering this, a small first integration can be scoped as the Automation Sprint (€1,690, fixed scope), agreed in writing before work starts. Larger or unusual integrations are scoped separately after a technical review of the systems involved. See Workflow Automation & Systems Integration for how we deliver it.
Questions
Do I need a specification for a small integration?+
A short one, yes. Even a single flow benefits from a written field map and error rules, because that is where surprises hide.
Does LATYNEX offer ready-made connectors?+
No. Integrations are scoped per project via API or webhook after a technical review of each system, and what is possible depends on what those systems expose.
Who decides which system wins when values differ?+
The business owner of the data, not the developer. Write the rule into section 5 so it does not get decided by accident.
Should credentials go in the document?+
Never. Record where they are held and who manages them, and share the secrets themselves through a secure route.
Can I hand this specification to another vendor?+
Yes, that is one of its purposes. A clear specification lets you compare proposals on equal terms.