Concepts

A handful of ideas explain almost everything the API does.

Sources

A source is one system that holds records of people: a CRM, a website, a shop, a mailing list. An admin registers each source in the app and gives it a short code, such as CRM or SHOP: capital letters, digits and underscores, up to 20 characters.

Every API key belongs to one source, and every call acts on that source’s records only. The source’s code comes back on records you read, as sourceSystemCode.

Samesake never writes to your systems. They stay the owners of the details. Samesake keeps its own copy of what you send, and the links between records.

Records and their IDs

A record is one person as one of your sources holds them: a contact, a customer, a subscriber. It has a name, an email address, a date of birth, an address and phone numbers, and all of them are optional except one.

Each record has two IDs:

ID	Whose it is	What it looks like	Notes
sourceRecordId	Yours	Anything up to 100 characters, such as CRM-10042	Unique within a source. Two sources can use the same value. Spaces at either end are ignored.
recordId	Samesake’s	rec_ and 12 letters and digits, such as rec_7k2m9xq4ht3b	Made when the record is first sent, returned to you, and never changed.

Send your own ID with every record. Samesake uses it to tell whether a record is new or already known, so a record sent twice is one record. You can find a record by either ID. Store Samesake’s beside yours if you want to use it later: unlike a person ID, it never changes.

People and person IDs

A person is a group of records that Samesake has linked as the same human being. If your CRM and your shop both hold Priya Sharma, and Samesake links the two records, they’re one person, and both records show the same personId. A person can also have several records in one source: if your CRM holds Priya twice, the two records are linked. A personId is per_ and 12 letters and digits, such as per_5d9h2k7m3x8q.

The personId is the key to group by in a report or a workflow. Three things to know about it:

• It’s null until matching has looked at the record. Matching runs in the background.
• It can change. New or updated records can join two people into one, and removing a link can split one into two. An update to a record can even remove an automatic link, if the record no longer looks like a strong match.
• A record that no one else matches still gets a person: a person of one record.

Links are transitive. If A is linked to B and B to C, then A, B and C are one person.

Person ID redirects

When two people become one, one of the person IDs is retired and the records take the other. Samesake keeps a list of retired IDs and the ID that replaced each, so a report that stored the old one can find the new one. A redirect always points to the current ID in a single step, never along a chain. When a person splits, nothing is retired and there’s no redirect: the ID stays with the part that holds its oldest record, and the other parts get new IDs.

You read the redirects, and the whole identity map (every record’s recordId, sourceRecordId, source code and personId, with no personal details), through the OData feed that an admin opens up with a feed key. Power BI, Excel and Azure Data Factory read it directly.

Matching and review

Matching compares records from all of your sources, and within each one, so a duplicate in a single system is found too. It compares names, email addresses, dates of birth, addresses, postcodes and phone numbers. It copes with the mess in real data, such as nicknames, abbreviations, swapped fields and different phone formats, and it scores each pair it considers. When two records from different sources carry the same distinctive sourceRecordId (a long code or a GUID), that counts as evidence too. It never counts within one source, where each ID belongs to one record.

The score has three outcomes:

• A strong match is linked automatically.
• A doubtful match goes to the review queue in the app, where someone at your organisation sees both records side by side with the evidence, and confirms or rejects the pair.
• A weak match isn’t linked.

Decisions last. A confirmed link is never removed automatically: if later data weakens it, the pair comes back to the queue for another look. A rejected pair isn’t linked automatically. It can come back to the queue if later data makes it look like a strong match, and the reviewer decides again. Any decision can be undone, which puts the pair back in the queue.

You don’t call anything to start matching. It starts when you send or change a record. The API never waits for it: the response to a send says only that the record was saved.

Deleting a record

When a record is deleted in your system, send the delete to Samesake. It marks the record as deleted and removes everything personal that Samesake holds about it: the name, email address, date of birth, address and phone numbers, the cleaned-up copy used for matching, and the comparison details saved with the links and review items that touch it. The IDs, the links, the reviewers’ decisions and the audit trail stay, because they hold no personal details.

Sending a record that was deleted brings it back, with the same recordId, and matching looks at it again.

If your system can’t report deletions, send a complete list from time to time: a snapshot. Records missing from it are deleted. Delete a record and Send a complete list have the details.

Erasure

When someone asks to be erased, you delete their records in each of your systems, and Samesake follows when each system sends the deletion. Samesake doesn’t delete anything in your systems for you.

In the app, a data protection officer (or an admin) can mark a person as “erasure requested”. Samesake then lists the person’s records and shows which sources have deleted theirs, and marks the request complete when all of them have. A record that comes back after an erasure was requested, or one that matches the person by email address, phone number or name and date of birth, is held out of matching and flagged for the data protection officer, so an erased person doesn’t quietly return.

An example

Your CRM and your shop each hold Priya Sharma. You send both records. Samesake gives each a recordId, matches them, and gives both the same personId.

Source	Your ID	Samesake’s recordId	personId
CRM	CRM-10042	rec_7k2m9xq4ht3b	per_5d9h2k7m3x8q
SHOP	C-58210	rec_3n8p2w6c9r4d	per_5d9h2k7m3x8q