- An Enrichment Response Is Not Yet a Safe CRM Update
- Establish Record Identity and Field Ownership Before an Upsert
- Attach Provenance and History to Every Accepted Value
- Make Retries and Conflicts Safe Instead of Last-Write-Wins
- Treat Rollback as a Tested Part of the Integration
- Frequently asked questions
A CRM enrichment API is safe when it resolves a CRM record through a stable external identity, applies an explicit field-precedence rule, and retains enough history to reverse a bad update. A successful lookup is evidence to evaluate, not permission to overwrite an authoritative value.
An Enrichment Response Is Not Yet a Safe CRM Update
A CRM enrichment API is not simply the service that returns company or contact attributes. Its consequential moment is the CRM write. When I review the approved Salesforce REST API page, I start by separating what the interface documents from what the integration still has to decide. The page says that a record can be inserted or updated through a specified external-ID field, checked September 2026. I read that as a stable addressing capability. I do not read it as permission to replace whichever CRM value happens to be present. What does the response actually authorize? It gives you a candidate value and an API route to a record. It does not tell you whether this record is the intended record, whether the destination field is already authoritative, or whether a later operator can undo the change. If you let a plausible response settle those questions by itself, your CRM has converted transport success into a field decision. When you keep the decision at the write boundary, you can ask the narrower question that matters: should this candidate change this field on this identified record under your stated rule?
Treat returned data as a candidate value, not automatic replacement
Before you write, ask what state this returned value is asking the CRM to change. It may fill a blank, challenge an existing value, or disagree with an owner or another system. Those are different decisions. If you treat all three as an upsert, the API response becomes an unexamined overwrite rather than a candidate for a field decision.
Separate matching clues from the stable identity of the CRM record
A name, domain, or email-like clue can help you find a possible match. Do not let it quietly become the durable identity for later retries. Choose the stable external identifier the CRM recognizes for the write path, then make the repeat request use it too. You are not claiming that every match is certain. You are preventing a repeat from becoming a differently targeted decision.
Establish Record Identity and Field Ownership Before an Upsert
The write path needs two decisions before an upsert: which record is being addressed, and who is allowed to change each field on it. In my document review, I put those decisions next to the two approved Salesforce history pages rather than treating history as an afterthought. Salesforce says field history tracking records changes for selected fields on selected objects. Its Field Audit Trail documentation adds that tracking must be enabled for the relevant objects and fields before history is retained, both checked September 2026. I take care not to turn those documents into a promise that every field is already auditable. They describe controls that you have to configure around the write path. That separation is useful because it stops a technically valid update from displacing a more authoritative value without a trail. If you cannot name the record identity, you have not made the first decision. If you cannot name the field authority, you have not made the second. And if you have not verified the relevant history configuration, you should not assume a later rollback will have the record it needs.
Use an external ID so the same request remains idempotent
Write the external identifier into your integration contract, not a later implementation note. Salesforce describes upserting through a specified external-ID field, checked September 2026. Use that documented pattern to anchor repeat behavior: the same candidate addresses the same record again. If you cannot establish that identity, hold the candidate for review rather than guess which record should receive it.
Assign every destination field an authority and precedence rule
Name each field's authority before a value arrives. Your rule may reserve it for a CRM owner, let an approved source fill blanks, or require review for equal authorities. You do not need a universal hierarchy. An OKKI Go research candidate can remain context until your rule authorizes a write.
Attach Provenance and History to Every Accepted Value
A value without its decision context is difficult to correct. In my field notes for an interface review, I keep the question attached to the value: what produced it, when was it observed, which external identity addressed the record, what was there before, and which rule accepted the write? I am not treating those notes as a provider guarantee. I am making the next inspection possible. If you retain only the latest field value, you cannot tell whether a later candidate is new information, a conflict, or another delivery of the same assertion. If you retain the acceptance context, you can read the next event against the earlier decision instead of reconstructing it from memory. This is also where a small design choice changes the recovery path. A source name without an observation time is incomplete. A prior value without the accepting rule is incomplete. A retry without the stable identity is incomplete. When I review a proposed schema, I look for those gaps before I would call the write path reversible, because each missing item forces the next reviewer to infer why the record changed.
Keep source, observation time, and acceptance context with the field
Provenance should answer a practical question, not decorate the record. When you see a value, you should be able to tell what produced it, when it was observed, and which policy accepted it. That makes the field usable without pretending it is permanent. It also separates a fresh delivery from a fresh observation when you are deciding whether to replace or retain a value.
Use field history to reconstruct what changed and why
Salesforce documents field history for selected fields and objects, and says Field Audit Trail depends on tracking being enabled for the relevant fields and objects, checked September 2026. Decide which enrichment-touched fields need history, then verify the configuration before automation. Do not assume it exists after a disputed bulk write.
Make Retries and Conflicts Safe Instead of Last-Write-Wins
The risky retry succeeds after the record has changed for another reason. In my API write-path review, I ask to see the state the original decision expected and the state the retry now encounters. You should compare them before a conditional write. Preserve a stronger authority, or apply your documented rule for a same-authority change. The comparison, not a successful HTTP exchange, tells you whether the old instruction still fits the record.
Read the current field state before a conditional write
Make the retry compare against the recorded decision context, not just a blank field. The request should resolve through the same external identity, but you may now see a different value, source, or authority. That comparison lets you distinguish a harmless repeat from a stale instruction and gives the operator a reason to hold it.
Quarantine ambiguous matches and equal-precedence disagreements
Do not make an ambiguous identity or equal-precedence conflict look resolved because the API can write a field. Quarantine the candidate with its source and competing values. An OKKI Go research workflow can keep it as context while the CRM record remains unchanged. This article governs safe writes, not provider ranking or waterfall selection.
Treat Rollback as a Tested Part of the Integration
Scenario assumption: an integration receives a candidate CRM value, stable external ID, source, observation time, and prior value. It may write only when its precedence rule is met. The mechanism change is a recorded, reversible enrichment event. The observable result is a bad event that can be identified without discarding later edits. The decision consequence is to enable unattended writes only after this reversal path is tested.
- Record the prior value and the accepted enrichment event before the update is treated as complete.
- During rollback, restore only the value attributable to that event, then re-read the field before changing anything that may have been edited later.
- Run the same failure path on a limited bulk set before allowing a bulk job to write without review.
Reverse one enrichment event without erasing later edits
A rollback should be narrow. Find the enrichment event, compare the current field with its written value, and restore only when that comparison still supports it. If you see a later approved edit, preserve it and send the discrepancy to review. You avoid false safety when reversal does not erase an intervening decision.
Test bulk-write failure paths before automation is enabled
A rollback plan helps only if you retained the identity, history configuration, and event context for a specific change. Salesforce's field-history documentation, checked September 2026, is a reminder to verify relevant fields and objects first. Test rejected matches, repeats, conflicts, and later edits before bulk automation.
A CRM enrichment API earns automation only after its write boundary is defined. Resolve the stable record identity, name the authority for the field, retain the decision context, and test a narrow rollback. Then a returned value can be useful without being mistaken for permission to rewrite the CRM.
Frequently asked questions
What does a CRM enrichment API describe at the write boundary?
It describes a candidate CRM update and the controls needed to accept, hold, or reverse it. The returned attribute is only one input. The record identity, field authority, and write history determine whether that candidate may safely change the CRM.
What evidence should remain attached to an accepted CRM enrichment value?
Keep the source, observation time, stable record identity, prior value, and the rule that accepted the update. These details let a reviewer distinguish a retry, a conflict, and a later edit without treating the current field as self-explanatory.
What boundary limits rollback for a CRM enrichment API?
Rollback is limited by what the integration retained and configured before the write. It should reverse one identifiable enrichment event, not erase a later approved edit or guess at a record when the stable identity is ambiguous.
When should a CRM enrichment API change the next action?
It should proceed only when the candidate addresses the intended record and satisfies the field's precedence rule. An ambiguous match or equal-precedence disagreement should become a reviewable event, not an automatic overwrite.
