Skip to content
Samesake
Menu

Quick start

By the end of this page you’ll have sent one made-up person to Samesake, read it back and seen it in the app. You’ll need to sign in as an admin, and a terminal with curl.

Register a source

Section titled “Register a source”

A source is one of your systems: a CRM, a website, a shop. Each source has its own API key, and a key can only touch its own source’s records.

  1. Sign in at app.samesake.co.uk as an admin.
  2. Open Admin, then Sources, then choose Register source.
  3. Give it a short Code such as CRM: letters, digits or underscores, up to 20, and Samesake shows them in capitals. Give it a Name, such as “Customer relationship management”. Leave Warn after empty for now.
  4. Choose Register.

Issue an API key

Section titled “Issue an API key”
  1. On the new source’s row, choose Issue API key.
  2. Copy the key from the box that appears. It starts mk_, and it’s shown once: Samesake keeps only a scrambled copy, so it can’t show it to you again. If you lose it, issue another and revoke the lost one.

The examples below use a placeholder key. It has the right shape, but it isn’t real, so the API will answer 401 until you swap in your own.

mk_abcd1234_0123456789abcdefghjkmnpqrstvwxyz

Send your first record

Section titled “Send your first record”

The record is made up: its email address is at example.com and its phone numbers are in the ranges set aside for drama. Send a made-up person for your first try, not a real customer. You’ll delete it at the end.

Replace the key with yours. The examples use bash or zsh syntax: on Windows, use Git Bash, or the PowerShell version below.

Terminal window
curl -i -X POST https://app.samesake.co.uk/api/v1/records \
  -H "X-Api-Key: mk_abcd1234_0123456789abcdefghjkmnpqrstvwxyz" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceRecordId": "CRM-10042",
    "title": "Ms",
    "firstName": "Priya",
    "lastName": "Sharma",
    "email": "priya.sharma@example.com",
    "dateOfBirth": "1986-04-03",
    "addressLine1": "14 Larch Grove",
    "addressLine2": "Manchester",
    "postcode": "M20 6RT",
    "phones": ["07700 900123", "0161 496 0123"]
  }'

Try it in the API reference

sourceRecordId is your own ID for the record, such as the contact ID in your CRM. It’s the only field you have to send. The header Content-Type: application/json matters: without it, curl sends the body as a form and the API answers 415.

You should see 201 Created, and a body with Samesake’s ID for the record:

Response: 201 Created
{ "recordId": "rec_7k2m9xq4ht3b" }

Keep that recordId. It’s Samesake’s permanent ID for this record, and you can store it beside your own.

Windows PowerShell (5.1 or later) doesn’t read curl’s quoting, so send the same record with Invoke-RestMethod:

Terminal window
$headers = @{ 'X-Api-Key' = 'mk_abcd1234_0123456789abcdefghjkmnpqrstvwxyz' }
$body = @'
{
  "sourceRecordId": "CRM-10042",
  "title": "Ms",
  "firstName": "Priya",
  "lastName": "Sharma",
  "email": "priya.sharma@example.com",
  "dateOfBirth": "1986-04-03",
  "addressLine1": "14 Larch Grove",
  "addressLine2": "Manchester",
  "postcode": "M20 6RT",
  "phones": ["07700 900123", "0161 496 0123"]
}
'@
Invoke-RestMethod -Method Post -Uri 'https://app.samesake.co.uk/api/v1/records' -Headers $headers -ContentType 'application/json' -Body $body

Send it again

Section titled “Send it again”

Send the same command again. This time Samesake finds a record with that sourceRecordId and updates it, so you get 200 OK and the same recordId. Sending a record twice never makes two records. That’s what makes it safe to retry.

Read it back

Section titled “Read it back”

Ask for the record by your own ID:

Terminal window
curl -i https://app.samesake.co.uk/api/v1/records/by-source-id/CRM-10042 \
  -H "X-Api-Key: mk_abcd1234_0123456789abcdefghjkmnpqrstvwxyz"

Try it in the API reference

In Windows PowerShell:

Terminal window
$headers = @{ 'X-Api-Key' = 'mk_abcd1234_0123456789abcdefghjkmnpqrstvwxyz' }
Invoke-RestMethod -Uri 'https://app.samesake.co.uk/api/v1/records/by-source-id/CRM-10042' -Headers $headers

You should see 200 OK and the record:

Response: 200 OK
{
  "recordId": "rec_7k2m9xq4ht3b",
  "sourceSystemCode": "CRM",
  "sourceRecordId": "CRM-10042",
  "title": "Ms",
  "firstName": "Priya",
  "lastName": "Sharma",
  "email": "priya.sharma@example.com",
  "dateOfBirth": "1986-04-03",
  "addressLine1": "14 Larch Grove",
  "addressLine2": "Manchester",
  "postcode": "M20 6RT",
  "phones": ["07700 900123", "0161 496 0123"],
  "personId": null,
  "deleted": false,
  "linkedRecords": []
}

personId is null because matching hasn’t looked at the record yet. It runs in the background, so give it a little while and ask again. Once the record is matched, personId holds the ID of the person it belongs to, and linkedRecords lists the IDs of the records Samesake has matched to it, from any source, including this one: two records in one system can be the same person.

See it in the app

Section titled “See it in the app”

Open https://app.samesake.co.uk/records/ followed by your recordId, for example https://app.samesake.co.uk/records/rec_7k2m9xq4ht3b. Until matching has grouped the record, the page says so. After that, the person appears on the People page, with the record under them.

Delete the test record

Section titled “Delete the test record”
Terminal window
curl -i -X DELETE https://app.samesake.co.uk/api/v1/records/by-source-id/CRM-10042 \
  -H "X-Api-Key: mk_abcd1234_0123456789abcdefghjkmnpqrstvwxyz"

Try it in the API reference

In Windows PowerShell:

Terminal window
$headers = @{ 'X-Api-Key' = 'mk_abcd1234_0123456789abcdefghjkmnpqrstvwxyz' }
Invoke-RestMethod -Method Delete -Uri 'https://app.samesake.co.uk/api/v1/records/by-source-id/CRM-10042' -Headers $headers

You should see 204 No Content (PowerShell prints nothing). Samesake removes the record’s details straight away. Its IDs stay, and so does its history. Delete a record has the details.

If something went wrong

Section titled “If something went wrong”
You see Why What to do
401 Unauthorized The key is missing, mistyped or revoked. The placeholder key in these examples is none of those, but it isn’t a real key either. Check the X-Api-Key header and use the key Samesake showed you.
415 Unsupported Media Type The body wasn’t sent as JSON. Add -H "Content-Type: application/json".
400 Bad Request The body isn’t valid JSON, or a field breaks a limit. Read the errors in the response: it names the field and says why.
429 Too Many Requests More than 600 requests a minute with this key. Wait the number of seconds in the Retry-After header.

Errors and limits covers every status code.

What next

Section titled “What next”