---
title: "Using the IDs"
description: "How another system looks up the identity of a row, keeps a copy that follows merges and splits, and what to store."
url: https://spool.alexpatow.com/docs/using-the-ids
docs_index: https://spool.alexpatow.com/llms.txt
---

# 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](https://spool.alexpatow.com/docs/getting-started.md) ends. If you have that project and its server is running, use it. If not, this makes it:

```sh
spool init companies
cd companies
```

```sh
spool dev
```

Leave that running. In a second terminal, in the `companies` directory:

```sh
spool load samples/crm-1.csv
spool match
spool load samples/crm-2.csv
spool match
```

## What 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

```sh
curl -s 'http://127.0.0.1:7765/v1/records?source=crm&key=c-7'
```

```text title="Output"
{"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:

```sh
spool show records crm:c-7
```

```text title="Output"
record    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 Logistics
```

## Many rows in one call

`POST /v1/records/identities` takes record IDs and answers where each is now:

```sh
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'"]}'
```

```text title="Output"
{"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:

```sh
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'"}]}'
```

```sh
curl -s http://127.0.0.1:7765/v1/identities/$KESTREL
```

```text title="Output"
{"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:

```sh
curl -s 'http://127.0.0.1:7765/v1/changesets?after=2'
```

```text title="Output"
{"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:

```sh
curl -s -X POST http://127.0.0.1:7765/v1/changesets/3/undo -d '{"reason": "that was only an example"}'
```

```sh
curl -s 'http://127.0.0.1:7765/v1/changesets?after=3'
```

```text title="Output"
{"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](https://spool.alexpatow.com/docs/concepts/matching.md#the-cost-of-ids-that-stay) 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:key` in one call.
- No client library. The calls above are the interface. `spool schema` prints the JSON Schema of the API's answers.
