When the same term means different things

The same term can refer to different things across a software setup. An “account” might identify a person signing in, a subscription, a bank account or an entry in a chart of accounts. Treating these as interchangeable can make an integration look correct while changing the meaning of its data.

Before automating the connection, establish which objects the workflow needs to distinguish. Give them stable identities, record their relationships and keep external identifiers tied to their source.

The aim is a model that preserves the meanings needed for the task. It should be no more elaborate than that task requires.

Start with the task

“Connect the account” sounds like a clear requirement until someone has to implement it. In an accounting setup, the next question might be:

• Which person is signing in?
• Which business subscription are they managing?
• Which bank account supplies the transactions?
• Which ledger account classifies an entry?

Consider a fictional service used by two organisations. Each organisation has a subscription; several people can sign in and work within it. A screen labelled “Account owner” could mean the person responsible for billing, the administrator who grants access, or the organisation receiving the service. Define which responsibility the screen represents and how it relates to the others.

The same distinction applies across providers. An integration can preserve each provider’s field name while mapping it to a clearly defined concept in the application. The interface can then use wording familiar to the people doing the task. A display label can vary between organisations or languages while the underlying identity and rules stay stable.

Describe the action before choosing the field or API resource. Signing in, changing a subscription and connecting a bank feed involve different objects. A generic account identifier does not tell an integration which one is intended.

This makes the model easier to challenge. Can one person work with several businesses? Can changing a subscription contact leave transaction access unchanged? Use the product’s documented rules and representative tasks to answer those questions before automating the connection.

Separate concepts that change independently

A person’s sign-in identity, a business’s service relationship, a bank account and a ledger category have different responsibilities. An integration may need only some of them. Distinguish the ones its task actually uses.

Changing who administers a subscription does not inherently change who owns a bank account. Renaming an expense category does not create a new person or service relationship. Keep each object’s identity, permissions and history tied to what it represents.

Apply the same test elsewhere. An organisation can hold several commercial accounts. An address can change without creating a new organisation. A document and its revisions may need separate identities because references must sometimes point to a particular version.

Separate concepts when their rules, relationships or histories differ in ways the software must preserve. Avoid adding speculative layers merely because another system might eventually need them.

The interface can still provide a concise account overview. A clear internal model need not expose every distinction on every screen.

Keep identity separate from labels

Names change, repeat and contain errors. They help people recognise a record but often make poor identifiers.

Use a stable internal identifier where the domain needs one. Store external identifiers with their source system and relevant account or namespace. An identifier that is unique within one provider account may not be unique across all accounts.

A mapping should say which internal object an external record represents. Record validity periods or previous mappings when changes affect historical interpretation. For ambiguous matches, preserve the candidate and the reason for uncertainty rather than silently merging records.

Rules or models can propose a match. Similar spelling does not establish identity. A consequential merge needs checks appropriate to what it will change, and a review path when the available evidence cannot decide it.

In the accounting example, a provider’s category code remains useful. Store it as a reference to that category in the relevant business context. Do not place user identities, subscription references and category codes in one undifferentiated account field.

Decide who owns each value

One system may own a business contact while another supplies bank transactions. Assign responsibility at the level needed by the integration instead of declaring one platform authoritative for everything.

For a material value, identify the allowed writer, update direction, expected delay and response to conflict. Decide what the application shows when the source is unavailable or stale.

Timing matters. Two systems can disagree legitimately while a transfer is in progress. Reconciliation must account for that window instead of treating every difference as an error or ignoring differences indefinitely.

Keep source data available where it is needed to investigate a transformation. Record corrections and their basis when they affect reporting or traceability. The goal is to explain how a value reached its current state without retaining unnecessary copies of sensitive records.

Preserve history through change

A display-name correction differs from an organisation merger or a replacement service account. The model should represent the change that actually occurred.

Updating a label may be enough for a spelling error. A retired category may need a successor relationship. A duplicate record may point to a canonical record while old references remain traceable. Use effective dates where reports must reflect the structure that existed at the time of an event.

Do not add a complete event-sourcing system simply to preserve a few important changes. Choose the lightest history mechanism that answers the product's real questions and supports recovery from a mistaken correction.

Test agreement, not just successful requests

An API success response means a request completed according to that interface. It does not prove that both systems now represent the same business state.

Check meaningful relationships and totals. Imported transactions may need valid category mappings; pending events may need a maximum age; counts may need to agree after a defined processing delay. Make discrepancies understandable enough that someone can investigate them.

Test changes as well as current data: a second business, a changed account contact, a retired category, an uncertain duplicate and a renamed external identifier. These cases expose assumptions that a clean initial import can miss.

Building software alongside the people who use it explains how to uncover these meanings in practice. Follow the task, distinguish the objects it depends on, and keep that meaning stable as data moves between systems.