Using the IDs
How another system looks up the identity of a row, keeps a copy that follows merges and splits, and what to store.
Spool's output is an ID for each real-world thing. This page is for the system that uses those IDs: a warehouse table, a CRM sync, a search index. It covers looking up one row, looking up many, keeping a copy that follows the log, and what an ID promises.
Before you start
The examples use the sample project with both of its files of rows loaded and matched, which is where Getting started ends. If you have that project and its server is running, use it. If not, this makes it:
spool init companies
cd companiesspool devLeave that running. In a second terminal, in the companies directory:
spool load samples/crm-1.csv
spool match
spool load samples/crm-2.csv
spool matchWhat to store
Store the identity ID beside your own row, and keep the row's source and key. The identity ID is the join key across systems. The source and key are how you ask again.
- An identity ID is a UUID that is minted once, when the identity is created. It does not depend on which records the identity holds, and it does not change when records join or leave.
- A record's ID is derived from its source, its key and its content, so the same row has the same record ID in every store. A changed row is a new record with a new ID under the same key.
The identity of one row
curl -s 'http://127.0.0.1:7765/v1/records?source=crm&key=c-7'{"records":[{"id":"bdbab4b2-e260-2b34-b08f-3fae6a2018a9","entity_type":"company","source":"crm","key":"c-7","payload":{"country":"GB","id":"c-7","name":"Larkfeild Logistics"},"label":"Larkfeild Logistics","evidence":null,"loaded_at":"2026-11-18T21:49:05.335185Z","load_run":4,"identity":"01a1efc6-41cd-775d-8758-e733aa086f7d","supersedes":null,"superseded_by":null,"retracted":null}],"next":null}identity is the answer. It is null for a record that no match has placed yet, or that waits in a review item. A key whose row changed has one record for each version, and each has an identity.
From the command line:
spool show records crm:c-7record bdbab4b2-e260-2b34-b08f-3fae6a2018a9
type company
source crm
key c-7
loaded 2026-11-18T21:49:05Z by run 4
identity 01a1efc6-41cd-775d-8758-e733aa086f7d
payload
country GB
id c-7
name Larkfeild LogisticsMany rows in one call
POST /v1/records/identities takes record IDs and answers where each is now:
A=$(spool show records crm:c-1 | awk '/^record/ {print $2}')
B=$(spool show records crm:c-8 | awk '/^record/ {print $2}')
curl -s -X POST http://127.0.0.1:7765/v1/records/identities -d '{"records": ["'$A'", "'$B'"]}'{"identities":["01a1efc6-41cd-775d-8758-e7300637659a","01a1efc6-42c0-7776-b736-83fde0cb4498"]}It takes record IDs and not source:key, so a caller that holds only keys lists the records of a source first: GET /v1/records?source=crm&limit=1000, then after=<next> for the following page.
An ID that was merged away
When two identities are merged, one ID survives and the other stops being current. It is never deleted or given to something else. Merge Kestrel Analytics into Larkfield Logistics, wrongly, to see it:
KESTREL=$(spool show records crm:c-8 | awk '/^identity/ {print $2}')
LARKFIELD=$(spool show records crm:c-4 | awk '/^identity/ {print $2}')
curl -s -X POST http://127.0.0.1:7765/v1/changesets -d '{"reason": "an example of a merge", "ops": [{"op": "merge", "from": "'$KESTREL'", "into": "'$LARKFIELD'"}]}'curl -s http://127.0.0.1:7765/v1/identities/$KESTREL{"id":"01a1efc6-42c0-7776-b736-83fde0cb4498","current":"01a1efc6-41cd-775d-8758-e733aa086f7d","entity_type":"company","label":"Larkfield Logistics","created":2,"members":[{"record":"4b1bc703-9041-0989-d0eb-4df5e9eae0f2","source":"crm","key":"c-4","since":1},{"record":"7da2b0d2-3601-e533-efa5-e1068cce5344","source":"crm","key":"c-8","since":3},{"record":"bdbab4b2-e260-2b34-b08f-3fae6a2018a9","source":"crm","key":"c-7","since":2}]}The old ID still answers. id is the ID that was asked for, current is the identity that took its place, and the records are that identity's. A system that stored the old ID stores current in its place. Until it does, lookups by the old ID keep working.
Follow the log
Every change to an identity is a changeset in an append-only log, and each has a position. A system that keeps its own copy reads the log from the position it last saw:
curl -s 'http://127.0.0.1:7765/v1/changesets?after=2'{"changesets":[{"seq":3,"changeset":{"id":"01a1f0a8-29d3-73c2-bdf9-ba39307ffdce","base":2,"actor":"user:01a1f0a8-28ad-7645-929c-9605cdf00bc4","reason":"an example of a merge","run":null,"ops":[{"op":"merge","from":"01a1efc6-42c0-7776-b736-83fde0cb4498","into":"01a1efc6-41cd-775d-8758-e733aa086f7d"}]},"content_hash":"bf700d416238efff21597374c5ec44eb018849908e67ce7a5404486fbd82bb93","started_by":null}],"head":3}head is the last position there is. Each operation says what changed:
| Operation | What a copy does |
|---|---|
create_identity | Nothing until a record is placed in it |
assign | Set the identity of record to to. to is null when the record leaves without joining another |
merge | Rewrite every row that has from to into |
reinstate | An undo of a merge. The assign operations beside it say which records go back |
constrain, unconstrain | Nothing. These bind later changes, not the current state |
The loop is: remember a position, ask for after=<position>, apply the operations in order, remember the last seq you applied, and ask again while it is below head. A page holds 100 changesets unless limit says otherwise, up to 1,000.
The undo of the merge above arrives the same way, as one more changeset:
curl -s -X POST http://127.0.0.1:7765/v1/changesets/3/undo -d '{"reason": "that was only an example"}'curl -s 'http://127.0.0.1:7765/v1/changesets?after=3'{"changesets":[{"seq":4,"changeset":{"id":"01a1f0a8-2a06-7027-9fd8-1ef410fb54ac","base":3,"actor":"user:01a1f0a8-28ad-7645-929c-9605cdf00bc4","reason":"that was only an example","run":null,"ops":[{"op":"reinstate","identity":"01a1efc6-42c0-7776-b736-83fde0cb4498"},{"op":"assign","record":"7da2b0d2-3601-e533-efa5-e1068cce5344","from":"01a1efc6-41cd-775d-8758-e733aa086f7d","to":"01a1efc6-42c0-7776-b736-83fde0cb4498"}]},"content_hash":"529193eda6b7eff9ecd1e8deb6525006efa07fd3bb6e221490e6cb9179b9f790","started_by":null}],"head":4}What changes an ID, and what does not
| Event | What happens to IDs |
|---|---|
| More rows arrive and match | Existing identities keep their IDs. New things get new IDs |
| A row changes | The new version joins or does not, by the rules. The identity keeps its ID |
| A rule changes | Nothing moves. A rematch suggests merges and does not make them |
| A merge | The into ID survives. The from ID answers with the other as current |
| A split | The identity that is split keeps its ID. The records that leave get a new one |
| An undo | A new changeset puts things back, with the IDs they had |
| A row is taken back | The record leaves its identity. The identity keeps its ID, even with no records left |
What this costs: IDs depend on the order records arrived in and on what the rules were at the time, so two stores loaded in different orders can disagree about which records share an identity. Matching has the detail.
What is not there
- No webhook and no stream. A consumer polls
GET /v1/changesets. - No export of all identities as a file. A copy is built by listing records and then following the log.
- No lookup of many rows by
source:keyin one call. - No client library. The calls above are the interface.
spool schemaprints the JSON Schema of the API's answers.