Skip to content
Faisal Mahmud TusherDigital marketing, SEO & analytics
with Faisal Tusher

Marketing Technology › The Marketing Stack

Documenting Marketing Integrations

How to document the integrations between marketing tools: one register of each connection, its fields, identifiers, schedule, consent filter, owner and checks.
Tutorialintermediate12 min readUpdated

Why integrations go undocumented

Integrations are easy to create and nobody's job to describe. A native connector is switched on in a few clicks during a trial and keeps running after the trial becomes a contract. An analyst sets up a scheduled export to a spreadsheet to answer one question and the spreadsheet becomes the source of a weekly report. An agency wires offline conversion uploads from the CRM into the ad accounts, and when the agency leaves, the business inherits a connection it never saw. None of these is a mistake when it is made. Together they produce a stack whose wiring exists only in the settings screens of each tool.

The cost arrives later and all at once. A tool is replaced and three reports stop updating. A consent change is made in one system and an audience upload elsewhere keeps sending people who withdrew. A password is rotated when someone leaves and an export fails silently for weeks. The marketing technology hub asks for a one-page data flow diagram in a first stack review; this tutorial produces the record behind that diagram, so the diagram can be trusted and kept current.

The register is not a migration plan. The tutorial on migrating to a new email platform keeps a register for one move; this one is permanent and covers every tool. Nor does it replace the documents that describe what flows: the tracking plan defines events, and the contract for a CRM sync is written in the guide to syncing the CRM and marketing platform. The register points to both.

Before you start

You need administrator access, or a colleague who has it, to each tool in the stack, because many connections are visible only in settings pages ordinary users cannot open. You need the stack inventory, however rough, listing each tool with its owner. You need the tracking plan, the measurement change log and any existing diagrams, even outdated ones, because an old diagram is a list of connections to check. And you need an hour with each person who runs scheduled reports, exports or uploads by hand, since those are the integrations least likely to appear anywhere.

Decide where the register lives. A shared spreadsheet or a table in the team's documentation space both work, as long as it has one owner, a change history and a place for each row's owner to sign off. Whatever the format, the integration register stays one document for the whole stack, with a row for every connection, rather than one list per tool. Agree accountability in advance with the RACI matrix: one person accountable for the register, one person accountable for each integration, and the people consulted before a connection is added or changed.

The steps

  1. List every connection you know about

    Start with what people can name. Go through the stack inventory tool by tool and ask its owner what it sends data to and receives data from. Write each connection as a row with a short name, the two tools and a one-line purpose ("send new leads from the website forms to the CRM", "upload qualified opportunities to the ad accounts"). Add the routes that run through the data layer: events into the warehouse, profiles and segments through a customer data platform (CDP) where the stack has one, and syncs back out to channels. Do not stop to fill in details yet; the aim of this step is a list long enough to show the shape of the stack.

  2. Find the ones nobody listed in each tool's settings, scheduled exports and the people who run them

    Now look rather than ask. Open each tool's integration, connected apps, webhook and API key settings and note every connection, active or not, that is not on the list. Many connections are configured on the receiving side, so check both ends. Look for scheduled exports and saved reports that send files somewhere, and for spreadsheets that pull data on a timer. Ask each person who prepares a recurring report where its numbers come from and follow the answer back to a source. Include manual integrations: a list exported and uploaded by hand every week is an integration with a person as its connector. The agency offboarding checklist is a useful prompt here, because connections an agency built are the ones most likely to be missing.

  3. Record source, destination, direction and method

    For each row, record which tool data leaves and which it lands in. Where a connection runs both ways, record each direction separately or note which fields go which way, because direction is a property of the field, as the CRM sync guide sets out. Record the method in plain words: native connector, middleware, the data layer through a reverse sync, a webhook, a scheduled file, a server-side upload, or a person. The data flow guide names the patterns (batch or streaming, push or pull); note which one applies so that whoever reads the row knows how it is likely to fail.

  4. Record the objects, fields and identifier each one keys on

    Write which objects cross (contacts, companies, orders, events, audience members) and which fields. Where the list is long, link a mapping document and record the fields that matter most in the row. Then record the identifier the destination matches on: email address, customer id, a click identifier, a hashed contact detail. Identifier mismatch is one of the failure modes the data flow guide describes, and a register that records the key makes it visible before it creates duplicates. For server-side conversion routes, such as a Conversions API or an offline conversion import, record the stored identifier the upload depends on and the deduplication key shared with the browser event, as the guide to connecting the CRM to ads and analytics describes.

  5. Record the schedule, append or replace behaviour and consent filtering

    Record when each connection runs: on every event, on a schedule, or when someone remembers. Record whether the destination appends what arrives or replaces the list it matches; this is the destination's documented behaviour, so read its documentation and note what it says rather than assuming. Then record the consent filter: which records are excluded before anything is sent, on which field, and where that field comes from. A connection with no filter is not necessarily wrong, since some flows carry no personal data or rely on another basis, but the row should say so and say who decided. A connection that sends people who opted out is the consent leakage the data flow guide warns about, and the register is where it becomes visible.

  6. Record the credentials, who holds them and the owner

    For each row, record what the connection authenticates with (a named user's login, a service account, an API key, a token) and who in the business holds it. A connection running under a former employee's or an agency's credentials is a finding, not a detail: it fails the day that access is removed, and until then it gives access nobody manages. Move such connections to credentials the business controls, and record when they were last rotated. Then name the accountable owner: the person who answers when the connection breaks and who approves changes to it. Write a role as well as a name, so the row survives a reorganisation.

  7. Write the check that shows each one failing

    For every row, write down how anyone would know it had stopped. The data flow guide's checks are the starting point: freshness (did it run when expected), volume (did the usual amount arrive), completeness (did the identifiers and required fields arrive filled) and reconciliation (do the counts match the source). Pick the one that fits, say where it is checked and who sees the alert. The data quality guide covers these checks in more depth. When a check fails on a conversion or tracking route, the tracking outage response SOP is the procedure to follow; the register row tells the responder what the connection was supposed to do.

  8. Draw the diagram from the register

    Draw one box per tool and one arrow per row, labelled with the row's short name and the method. Group the boxes by layer, from collection through the data layer to activation and measurement, so that connections bypassing the data layer stand out. Mark rows with no owner, no failure check or credentials held outside the business in a different colour. The diagram is a view of the register, not a separate document: when a row changes, redraw the arrow. This is the one-page picture the stack review needs, and because every arrow traces back to a row, a question about any line on it has an answer.

  9. Keep the register current with every change

    Make the register part of change control. A new connection is not live until its row is complete and its owner has signed off. A changed connection updates its row and gets a dated entry in the measurement change log where it affects reporting. A removed connection keeps its row, marked retired with the date, so that a later question about old data has an answer; the tutorial on retiring a marketing tool depends on exactly this list of connections when a tool leaves. Review the whole register at each stack review, with every owner confirming their rows. Write the procedure down in the format the guide to writing a marketing SOP sets out, so the habit outlives the person who started it.

The integration register

Each row of the register carries the same fields. The table below lists them with what each records and why it matters; the column on the right is the reason a register is more useful than a diagram alone.

FieldWhat it recordsWhy it matters
Name and purposeA short name and the job the connection doesLets anyone tell whether it is still needed
Source and destinationThe tool data leaves and the tool it lands inShows what breaks when either tool changes
Direction and methodOne way or both; connector, middleware, reverse sync, webhook, file, server upload or personTells the reader how it is likely to fail
Objects and fieldsWhat crosses, with a link to the full mappingFinds the cause when a field arrives empty
IdentifierThe key the destination matches on, and any deduplication keyExplains duplicates and failed matches
ScheduleOn each event, on a schedule or by handSets what freshness means for this row
Append or replaceThe destination's documented behaviourPrevents lists growing forever or being wiped
Consent filterWhich records are excluded, on which field, decided by whomShows where consent could leak
CredentialsWhat it authenticates with and who in the business holds itFinds connections that will fail when someone leaves
OwnerThe accountable person and their roleGives every failure a first call
Failure checkHow a failure would be noticed and who sees itTurns a silent failure into an alert
Last changeThe date and a link to the change recordExplains a shift in the numbers

A meal kit company documents its integrations (illustrative)

Illustrative example — not a real result

Mubrovane Meal Kits builds its integration register

Mubrovane Meal Kits, an invented meal kit subscription business, starts its register with the 11 connections its marketing operations lead can name: the shop to the email platform, the shop to the CRM, form submissions to the CRM, the CRM to two ad accounts, and the analytics and shop exports into the warehouse, among others.

Looking inside each tool's settings adds 6 more. Two are native connectors switched on during trials and never used. One is a webhook from the subscription system to a text message tool that nobody in marketing knew existed. The most important is a scheduled export from the subscription system to a shared spreadsheet, running every Monday under the credentials of an analyst who left 5 months earlier. That spreadsheet feeds the weekly retention report the leadership team reads. Had the former analyst's account been closed, as the offboarding list said it should be, the report would have stopped updating with no error anyone could see.

The team moves the export to a service account the business holds, names the head of analytics as its owner and adds a freshness check: if the spreadsheet has not updated by Monday midday, the owner gets an alert. The two unused connectors are switched off and their rows marked retired. Every one of the 15 remaining rows now has an owner, a failure check and credentials held inside the business, and the diagram drawn from them fits on one page.

Verify it worked

Check the register against the stack, not against memory.

  • Every connection people named has a row, and so does every one you found in settings and scheduled exports.
  • Pick any row. You can read its source, destination, method, identifier, schedule, consent filter, credentials and owner without asking the builder.
  • Every row names a failure check, where it runs and who sees the alert.
  • The diagram has one arrow per live row. Rows with no owner, no check or outside credentials show in a different colour.
  • No row names a former employee or an agency as credentials holder, as in the Mubrovane example.

If it goes wrong

  • A report stops updating and no row explains it. The connection was never listed. Check both ends in each tool's settings, then add a row.
  • Duplicates or failed matches appear. The identifier is wrong or unrecorded. Record the key the destination matches on, and any deduplication key.
  • Opted-out people still reach an audience. The consent filter is missing or reads the wrong field. Record the field, its source and who decided.
  • An export fails after someone leaves. It ran on their credentials. Move it to credentials the business holds and record the rotation date.

Next steps

Common mistakes

  • Listing only what people remember. The connections that cause trouble are the ones in settings pages and scheduled jobs nobody thinks of. Look in every tool, on both ends.
  • Drawing the diagram instead of keeping the register. A picture without fields, identifiers, credentials and owners cannot answer the questions a failure raises.
  • Leaving out manual integrations. A weekly export and upload done by hand is a connection, and it is the first to stop when its person goes on leave.
  • Assuming append or replace. Record what the destination's documentation says; a wrong assumption either wipes an audience or grows a list forever.
  • Recording credentials as "the agency" or a person who has left. Move the connection to credentials the business controls before the access is removed.
  • No failure check. An integration without one fails silently, and the first sign is a decision made on stale numbers.
  • Treating the register as a one-off project. Without a rule that every change updates a row, it is out of date by the next quarter.

Frequently asked questions

Is a data flow diagram not enough?

A diagram shows that two tools are connected; it cannot show which fields cross, which identifier the match depends on, whether the destination replaces or appends, who holds the credentials or how anyone would notice a failure. Those are the details that decide whether a problem is found in an hour or in a quarter. Keep the register as the record and draw the diagram from it, so the picture is always a view of something more complete.

Who should own the integration register?

One person, usually in marketing operations, owns the register as a document: its format, its review and the rule that changes are recorded. Each integration in it has its own accountable owner, who may sit in another team. The register owner does not fix every broken sync; they make sure every row has someone who will, and that nobody adds a connection without adding a row.

How detailed should each entry be?

Detailed enough that someone who did not build the integration could tell whether it is working, what would break if it stopped and how to switch it off safely. That usually means the fields and the identifier, the schedule, the append or replace behaviour, the consent filter, the credentials holder, the owner and the failure check. Field-level mappings that run to many lines can live in a linked document, with the register pointing to it.

Terms used on this page

Frameworks

Where this page is used

Related