Synchronization and reconciliation
Combine timely change delivery with completeness checks, stable cursors and explicit ownership of every synchronized field.
On this page
Before you start
- Source and destination ownership
- A stable record identity
- An extraction and deletion policy
A change stream with a completeness pass
The event path provides timely updates. Reconciliation identifies records that the event path did not resolve.
Scroll across the diagram to see all four systems.
Deliver change
Preserve source identity, revision and operation type.
Apply owned fields
Map the record under the destination write policy.
Read bounded snapshot
Extract a consistent or explicitly bounded source view.
Read destination evidence
Compare matched identifiers and relevant field checksums.
Queue corrective work
Repair missing or divergent records under the same action identity rules.
Record reconciliation result
Close the difference only after confirmed destination state.
Write only what the integration owns
A field ownership register prevents two systems from continually overwriting each other. Record the owning source, destination representation, transformation and conflict rule. Treat identity, lifecycle stage, consent and commercial status as separate ownership decisions.
Keep external identifiers in explicit mappings. Email addresses, display names and phone numbers change and may not be unique. Record merge and deletion behavior so a source merge does not create a new unrelated destination record.
| Field class | Ownership decision | Reconciliation evidence |
|---|---|---|
| Stable identity | Preserve source ID and destination mapping. | One mapping per agreed source entity. |
| Lifecycle stage | Choose the authoritative transition policy. | Source revision and accepted destination transition. |
| Contact details | Define permitted source fields and normalization. | Relevant field checksum or version. |
| Consent | Preserve purpose, channel, source and effective time. | Current permission decision and provenance. |
| Deletion | Choose tombstone, archival or removal semantics. | Deletion marker and completed destination action. |
Advance a checkpoint after committed work
A checkpoint should identify what the pipeline can safely consider processed. Advancing it before durable destination outcome can skip work after a crash. Preserve the extraction cursor separately from processing completion when these stages are decoupled.
If a provider exposes only a modified timestamp, use its documented precision and ordering behavior. An overlap window plus stable identity can reduce missed changes around a boundary, but it is not a universal substitute for a transactional change log.
{
"connection_id": "connection_17",
"object_type": "contact",
"extraction": {
"cursor": "cursor_248",
"observed_at": "2026-09-14T10:30:00Z"
},
"processing": {
"last_committed_batch": "batch_81",
"unresolved": 3
},
"reconciliation": {
"snapshot": "snapshot_12",
"missing": 2,
"divergent": 1
}
}Reconcile identifiers before comparing totals
Matching row counts can hide one missing and one duplicated record. Compare identifiers first, then relevant versions or normalized field values. Document intentional exclusions, archived records and permissions that limit source visibility.
Choose a reconciliation window that can be reproduced. If the source changes during a long scan, preserve snapshot context or document the bounded consistency model. A difference caused by timing should not be mistaken for a permanent data loss.
Repair differences through the ordinary write path
A repair job should reuse mapping, authorization and idempotency rules. A special reconciliation script with broader permissions can reintroduce precisely the data errors that the normal pipeline prevents.
Classify differences as missing, divergent, deleted, excluded or unresolved. Assign each a next action and retain the comparison evidence. Only mark a repair complete after confirming the destination state, not when the corrective message was queued.
Make completeness measurable and explainable
Track extraction freshness, oldest unresolved item, mapping coverage and the last successful reconciliation. A green transport status does not establish that every eligible record reached its destination.
Test missed webhooks, source merges, deleted records, field normalization differences, cursor expiration and a permission change midway through extraction. Confirm that a resumed run neither skips the incomplete batch nor repeats a completed business action.
Inspect a reconciliation result
Compare eligible source and destination evidence and choose the next safe synchronization action.
/api/v1/connections/connection_17/reconciliationsExpected outcome
Comparison complete
No difference was found within the defined reconciliation scope.
{
"reconciliation_id": "reconcile_12",
"state": "complete",
"missing": 0,
"divergent": 0
}Content-Type: application/jsonDecision path
- Verify connection authority
- Read the bounded comparison set
- Compare identifiers and owned fields
- Record the scope and result
Input schema 4 fields
| Field | Type | Meaning |
|---|---|---|
cursor_validRequired | boolean | Whether source extraction can resume from this cursor. |
missing_recordsRequired | integer | Eligible source records absent from the destination.Minimum: 0 |
divergent_recordsRequired | integer | Matched records whose owned fields differ.Minimum: 0 |
permission_currentRequired | boolean | Whether the connection still has required access. |
Standards and documentation
Explore the protocol specifications and platform guidance for this topic.
Bring the contract into your operating environment.
Discuss an implementation