Skip to main content
Customers often send a full export first, then a delta a few weeks later that overlaps it. Importing the delta as a new migration would duplicate every record that was already migrated. A checkpoint avoids that. A checkpoint is a new migration, with its own migration ID, files, runs and results, created from an earlier migration. The first migration and every checkpoint after it form a group. When a checkpoint skips records already migrated (the default), each of its imports leaves out every record whose source ID an earlier migration of the group already holds. Only net-new records are imported, and nothing that was migrated before is updated or overwritten.

How records are matched

Records are matched on each template’s unique column — the column holding the source system’s record ID (for example a Legacy ID). The agent carries that ID through unchanged, so a record in the delta that was in an earlier export is recognised and left out. A unique column that is calculated (a formula) works too: it’s filled in before matching. A column filled by AI extraction is never used for matching, because it isn’t a source ID.
  • “Earlier” means every migration of the group created before this checkpoint, not only the one it was created from. Checkpoint 3 skips what the first migration, checkpoint 1 and checkpoint 2 imported.
  • A record that changed between exports is still skipped: checkpoints never overwrite.
  • A record with a blank source ID is always imported (there’s nothing to match it on).
  • A template with no unique column can’t be matched. Its records are all imported unless the agent finds the column that carries the source ID — and that column is used only if its values are unique to each record, both in the delta and within each earlier migration (the same ID appearing in two earlier migrations is fine). The run report lists such templates in unmatchedTemplates.
  • If an import’s output has no source ID column for a template that has one, the import stops rather than importing everything.
  • “Already migrated” means held in an earlier migration of the group, whatever happened to it afterwards. Deleting a checkpoint removes its records from what later checkpoints skip.
  • References to records migrated earlier (a new contact’s company, say) keep the source ID as usual and resolve against the earlier migrations.

Request

The body is the same as Create a migration, with two more fields:
string (uuid)
The ID of the migration this checkpoint is created from — the first migration or any checkpoint of its group. It must be a migration of your account (404, code: "checkpoint_base_not_found", otherwise). Archived migrations are allowed.
boolean
default:"true"
Leave out records an earlier migration of the group already holds. Set false to import everything in this checkpoint while still grouping it. Only valid with checkpoint_of.
A checkpoint uses the source and templates of the migration it’s created from: omit source and templates, or send the same ones (400 otherwise). Names stay unique. A checkpoint needs a name of its own; a name already used for the same source returns 409 with code: "name_taken". external_id idempotency works as usual. Re-sending an external_id with a different checkpoint_of (or one that isn’t a checkpoint) returns 409 with code: "external_id_conflict". Creating a checkpoint is also refused with 409 when the migration it’s based on is being deleted (code: "checkpoint_base_deleting"), or when that migration’s source no longer exists (code: "checkpoint_source_missing"). If Vern can’t read the base migration, you get 500 and nothing is created — try again.

Response

201 Created with the migration object, which shows where it sits in its group:
Then upload the delta and start a run as for any migration. The recipe that worked for the earlier migrations of the group is reused first.

What was skipped

A completed run’s report on a checkpoint carries:
integer
Records left out because an earlier migration of the group already holds them.
object[]
The same per sheet: { templateName, sheetId, keyColumn, skipped, keyRejected, priorKeysMissing }. keyRejected: the column named for the template doesn’t identify records, so nothing was skipped. priorKeysMissing: the earlier migrations hold no values in the key column, so nothing matched.
string[]
Readable reasons some sheets skipped nothing. Present only when there are any.
string[]
Templates with no source ID column to match on; all of their records were imported.
inserted counts only the new records. A delta whose records were all migrated before completes with inserted: 0.

Listing a group

Returns the first migration and every checkpoint of the group.

Changing a checkpoint

PATCH /migrations/{id} takes skip_migrated on a checkpoint; the change applies to runs started after it. A group keeps one source: neither a checkpoint’s source nor its first migration’s can be changed (409, code: "checkpoint_source_fixed"), and a checkpoint’s group is fixed once created. The first migration of a group can’t be deleted while it has checkpoints.