Documentation

Samesake finds the same person across your systems. Each of your systems sends it the records it holds about people, and Samesake matches them. You get stable IDs back, so a report or a workflow can say “these records are one person”.

These guides are for the developer, or the technically minded admin, who connects a system to the API. You don’t need to know anything about matching to follow them.

What you do

1. An admin registers each of your systems in Samesake as a source, and issues it an API key.
2. Each system sends its records to the API when they change: create or update a record, and delete it when it’s deleted. If a system can’t tell you about deletions, it sends a complete list from time to time instead.
3. Samesake matches the records in the background. People at your organisation review the doubtful matches in the app.
4. You read the result: every record has a personId, and the same person has the same one in every source.

Start here

• Quick start: register a source, issue a key, send a record and see it in the app. It takes under ten minutes.
• Authentication: how API keys work, how to rotate them and how to keep them safe.
• Concepts: sources, record IDs, person IDs, matching, review, deletion and erasure.

Send your records

• Send a record: create, update, replace and read a record, and what each field accepts.
• Send records in batches: up to 1,000 records in one request.
• Upload a CSV file: an admin loads a file in the app, with no code.
• Delete a record: what a delete does, and how to bring a record back.
• Send a complete list: a snapshot, for systems that can’t report deletions.

Read the identity map

• The identity map feed: the OData feed of every record’s ID against its person ID, and how to read it with a feed key.
• Power BI: load the feed into Power BI or Excel, and refresh it on a schedule.

Reference

• Errors and limits: every status code, the limits, and how to retry safely.
• API reference: every operation, with a “Try it” console.
• Changelog: what has changed in the API and these guides.

Before you start

You need a Samesake account, and an admin to issue the API key. If you don’t have an account yet, talk to us.

The API is at https://app.samesake.co.uk/api/v1. It speaks JSON over HTTPS. Call it from a server, not from a browser: the API allows browser calls only from the docs site’s origin (for the “Try it” console), and other origins get no CORS headers. A key in browser code is a key anyone can read.

The same description the API reference is drawn from is at /docs/api/openapi.json, if you want to generate a client.