Skip to content
Samesake
Menu

API reference as text

This is the API reference as plain text, for AI assistants and reading without JavaScript.

Send your systems’ records of people to Samesake, which matches them to find the same person across your systems.

Each API key belongs to one source: one of your systems, such as your CRM. Every call acts on that source’s records only. Send the key in the X-Api-Key header.

Keep Samesake up to date as your records change: create or update a record whenever it changes, and delete it when it’s deleted. If your system can’t tell you about deletions, send a complete list from time to time as a snapshot: records missing from it are deleted.

Errors are problem details (RFC 9457), with the content type application/problem+json. Each key can make up to 600 requests a minute.

Contents

Section titled “Contents”

Operations

Schemas

Servers

Section titled “Servers”
  • URL: https://app.samesake.co.uk

Tags

Section titled “Tags”

Records

Section titled “Records”

A record is what one source holds about one person. Address it by Samesake’s ID for it (recordId, returned when it’s created) or by your own (sourceRecordId).

Snapshots

Section titled “Snapshots”

A snapshot is a complete list of a source’s records, for systems that can’t report deletions. Open one, add every record to it in batches, then complete it: the source’s records that weren’t added are deleted. If that would delete more than 10% of the source’s records, nothing is deleted and the snapshot is held for an admin to check. Records created or changed after the snapshot was opened, by other calls, are never deleted by it.

Operations

Section titled “Operations”

Create or update a record

Section titled “Create or update a record”
  • Method: POST
  • Path: /api/v1/records
  • Operation ID: UpsertRecord
  • Tags: Records

Sends one record. If the source has no record with this sourceRecordId, it’s created (201); if it has, that record is updated (200). Matching follows in the background.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Request body

Section titled “Request body”

Required: true

Content type: application/json

RecordInput

A record as your system holds it. Every field except sourceRecordId is optional, and each request sends the whole record: a field left out or sent as null is cleared. Values aren’t rejected for being badly formed: a date, phone number or postcode Samesake can’t read is kept as sent, but not used for matching.

Example:

{
  "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"
  ]
}

Responses

Section titled “Responses”
200 Updated, or unchanged if the record already had these details.
Section titled “200 Updated, or unchanged if the record already had these details.”

Content type: application/json

RecordIdResponse

The record written.

Example:

{
  "recordId": "rec_7k2m9xq4ht3b"
}
201 Created: the source had no record with this ID.
Section titled “201 Created: the source had no record with this ID.”

Headers:

  • Location

    Where to get the new record: /api/v1/records/{recordId}.

    string

    Example:

    "/api/v1/records/rec_7k2m9xq4ht3b"

Content type: application/json

RecordIdResponse

The record written.

Example:

{
  "recordId": "rec_7k2m9xq4ht3b"
}
400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.
Section titled “400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.”

Content type: application/problem+json

HttpValidationProblemDetails

What went wrong, as a problem details object (RFC 9457), with errors when a field breaks a limit.

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "sourceRecordId": [
      "sourceRecordId is required."
    ]
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
409 Another request changed the same record at the same time. Retry the request.
Section titled “409 Another request changed the same record at the same time. Retry the request.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "The record was changed by another request at the same time. Retry the request.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.
Section titled “413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.14",
  "title": "Request body is too large.",
  "status": 413,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.
Section titled “415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.16",
  "title": "Unsupported Media Type",
  "status": 415,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Create or update records in a batch

Section titled “Create or update records in a batch”
  • Method: POST
  • Path: /api/v1/records/batch
  • Operation ID: UpsertRecords
  • Tags: Records

Sends up to 1,000 records at once, each created or updated as by Create or update a record. The batch is all or nothing: if any record isn’t valid, none is saved, and errors names each one by its position ([2].email). The results are in the order the records were sent.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Request body

Section titled “Request body”

Required: true

Content type: application/json

array of RecordInput, minItems: 1, maxItems: 1000

Example:

[
  {
    "sourceRecordId": "CRM-10042",
    "firstName": "Priya",
    "lastName": "Sharma",
    "email": "priya.sharma@example.com",
    "phones": [
      "07700 900123"
    ]
  },
  {
    "sourceRecordId": "CRM-10043",
    "title": "Mr",
    "firstName": "Tom",
    "lastName": "Fletcher",
    "dateOfBirth": "12/09/1979",
    "postcode": "M1 4BT",
    "phones": [
      "07700 900456"
    ]
  }
]

Responses

Section titled “Responses”
200 What happened to each record, in the order they were sent.
Section titled “200 What happened to each record, in the order they were sent.”

Content type: application/json

array of UpsertResult

Example:

[
  {
    "sourceRecordId": "CRM-10042",
    "recordId": "rec_7k2m9xq4ht3b",
    "outcome": "Created"
  },
  {
    "sourceRecordId": "CRM-10043",
    "recordId": "rec_3n8p2w6c9r4d",
    "outcome": "Updated"
  }
]
400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.
Section titled “400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.”

Content type: application/problem+json

HttpValidationProblemDetails

What went wrong, as a problem details object (RFC 9457), with errors when a field breaks a limit.

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "[1].email": [
      "email must be at most 200 characters."
    ]
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
409 Another request changed the same record at the same time. Retry the request.
Section titled “409 Another request changed the same record at the same time. Retry the request.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "The record was changed by another request at the same time. Retry the request.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.
Section titled “413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.14",
  "title": "Request body is too large.",
  "status": 413,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.
Section titled “415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.16",
  "title": "Unsupported Media Type",
  "status": 415,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Replace a record

Section titled “Replace a record”
  • Method: PUT
  • Path: /api/v1/records/{recordId}
  • Operation ID: ReplaceRecord
  • Tags: Records

Replaces every field of one of the source’s records with the fields sent: a field left out or sent as null is cleared. sourceRecordId in the body is ignored, because the path names the record. Replacing a deleted record restores it.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Path parameters

Section titled “Path parameters”

  • recordId (required): string

    Samesake’s ID for the record, returned when it was created.

    Example:

    "rec_7k2m9xq4ht3b"

Request body

Section titled “Request body”

Required: true

Content type: application/json

RecordReplacement

A record’s fields, replacing all of its current ones: a field left out or sent as null is cleared. There’s no sourceRecordId, because the path names the record (one sent anyway is ignored). Values aren’t rejected for being badly formed: a date, phone number or postcode Samesake can’t read is kept as sent, but not used for matching.

Example:

{
  "title": "Ms",
  "firstName": "Priya",
  "lastName": "Sharma",
  "email": "p.sharma@example.com",
  "dateOfBirth": "1986-04-03",
  "addressLine1": "3 Willow Court",
  "addressLine2": "Stockport",
  "postcode": "SK4 2DD",
  "phones": [
    "07700 900123"
  ]
}

Responses

Section titled “Responses”
200 Replaced.
Section titled “200 Replaced.”

Content type: application/json

RecordIdResponse

The record written.

Example:

{
  "recordId": "rec_7k2m9xq4ht3b"
}
400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.
Section titled “400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.”

Content type: application/problem+json

HttpValidationProblemDetails

What went wrong, as a problem details object (RFC 9457), with errors when a field breaks a limit.

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "phones": [
      "At most 10 phone numbers are allowed."
    ]
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
404 The source has no record with this ID.
Section titled “404 The source has no record with this ID.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Record not found.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
409 Another request changed the same record at the same time. Retry the request.
Section titled “409 Another request changed the same record at the same time. Retry the request.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "The record was changed by another request at the same time. Retry the request.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.
Section titled “413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.14",
  "title": "Request body is too large.",
  "status": 413,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.
Section titled “415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.16",
  "title": "Unsupported Media Type",
  "status": 415,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Delete a record

Section titled “Delete a record”
  • Method: DELETE
  • Path: /api/v1/records/{recordId}
  • Operation ID: DeleteRecord
  • Tags: Records

Deletes one of the source’s records. Its details are removed from Samesake straight away; its IDs and its history stay. Deleting a record that’s already deleted succeeds. Sending the record again later restores it.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Path parameters

Section titled “Path parameters”

  • recordId (required): string

    Samesake’s ID for the record, returned when it was created.

    Example:

    "rec_7k2m9xq4ht3b"

Responses

Section titled “Responses”
204 Deleted.
Section titled “204 Deleted.”
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
404 The source has no record with this ID.
Section titled “404 The source has no record with this ID.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Record not found.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
409 Another request changed the same record at the same time. Retry the request.
Section titled “409 Another request changed the same record at the same time. Retry the request.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "The record was changed by another request at the same time. Retry the request.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Get a record

Section titled “Get a record”
  • Method: GET
  • Path: /api/v1/records/{recordId}
  • Operation ID: GetRecord
  • Tags: Records

Returns one of the source’s records as Samesake holds it, with the person it belongs to and the IDs (not the details) of the records matched to it from any source. A deleted record is still returned, with deleted: true and its details cleared.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Path parameters

Section titled “Path parameters”

  • recordId (required): string

    Samesake’s ID for the record, returned when it was created.

    Example:

    "rec_7k2m9xq4ht3b"

Responses

Section titled “Responses”
200 The record.
Section titled “200 The record.”

Content type: application/json

RecordView

A record as Samesake holds it: its details as the source sent them (all cleared once it’s deleted), the person it belongs to, and the records matched to it.

Example:

{
  "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": "per_5d9h2k7m3x8q",
  "deleted": false,
  "linkedRecords": [
    {
      "recordId": "rec_3n8p2w6c9r4d",
      "sourceSystemCode": "SHOP",
      "sourceRecordId": "C-58210",
      "linkType": "Auto"
    }
  ]
}
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
404 The source has no record with this ID.
Section titled “404 The source has no record with this ID.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Record not found.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Replace a record by your ID

Section titled “Replace a record by your ID”
  • Method: PUT
  • Path: /api/v1/records/by-source-id/{sourceRecordId}
  • Operation ID: ReplaceRecordBySourceId
  • Tags: Records

Replaces every field of one of the source’s records with the fields sent: a field left out or sent as null is cleared. sourceRecordId in the body is ignored, because the path names the record. Replacing a deleted record restores it.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Path parameters

Section titled “Path parameters”

  • sourceRecordId (required): string

    Your ID for the record in this source.

    Example:

    "CRM-10042"

Request body

Section titled “Request body”

Required: true

Content type: application/json

RecordReplacement

A record’s fields, replacing all of its current ones: a field left out or sent as null is cleared. There’s no sourceRecordId, because the path names the record (one sent anyway is ignored). Values aren’t rejected for being badly formed: a date, phone number or postcode Samesake can’t read is kept as sent, but not used for matching.

Example:

{
  "title": "Ms",
  "firstName": "Priya",
  "lastName": "Sharma",
  "email": "p.sharma@example.com",
  "dateOfBirth": "1986-04-03",
  "addressLine1": "3 Willow Court",
  "addressLine2": "Stockport",
  "postcode": "SK4 2DD",
  "phones": [
    "07700 900123"
  ]
}

Responses

Section titled “Responses”
200 Replaced.
Section titled “200 Replaced.”

Content type: application/json

RecordIdResponse

The record written.

Example:

{
  "recordId": "rec_7k2m9xq4ht3b"
}
400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.
Section titled “400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.”

Content type: application/problem+json

HttpValidationProblemDetails

What went wrong, as a problem details object (RFC 9457), with errors when a field breaks a limit.

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "phones": [
      "At most 10 phone numbers are allowed."
    ]
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
404 The source has no record with this ID.
Section titled “404 The source has no record with this ID.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Record not found.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
409 Another request changed the same record at the same time. Retry the request.
Section titled “409 Another request changed the same record at the same time. Retry the request.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "The record was changed by another request at the same time. Retry the request.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.
Section titled “413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.14",
  "title": "Request body is too large.",
  "status": 413,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.
Section titled “415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.16",
  "title": "Unsupported Media Type",
  "status": 415,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Delete a record by your ID

Section titled “Delete a record by your ID”
  • Method: DELETE
  • Path: /api/v1/records/by-source-id/{sourceRecordId}
  • Operation ID: DeleteRecordBySourceId
  • Tags: Records

Deletes one of the source’s records. Its details are removed from Samesake straight away; its IDs and its history stay. Deleting a record that’s already deleted succeeds. Sending the record again later restores it.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Path parameters

Section titled “Path parameters”

  • sourceRecordId (required): string

    Your ID for the record in this source.

    Example:

    "CRM-10042"

Responses

Section titled “Responses”
204 Deleted.
Section titled “204 Deleted.”
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
404 The source has no record with this ID.
Section titled “404 The source has no record with this ID.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Record not found.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
409 Another request changed the same record at the same time. Retry the request.
Section titled “409 Another request changed the same record at the same time. Retry the request.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "The record was changed by another request at the same time. Retry the request.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Get a record by your ID

Section titled “Get a record by your ID”
  • Method: GET
  • Path: /api/v1/records/by-source-id/{sourceRecordId}
  • Operation ID: GetRecordBySourceId
  • Tags: Records

Returns one of the source’s records as Samesake holds it, with the person it belongs to and the IDs (not the details) of the records matched to it from any source. A deleted record is still returned, with deleted: true and its details cleared.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Path parameters

Section titled “Path parameters”

  • sourceRecordId (required): string

    Your ID for the record in this source.

    Example:

    "CRM-10042"

Responses

Section titled “Responses”
200 The record.
Section titled “200 The record.”

Content type: application/json

RecordView

A record as Samesake holds it: its details as the source sent them (all cleared once it’s deleted), the person it belongs to, and the records matched to it.

Example:

{
  "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": "per_5d9h2k7m3x8q",
  "deleted": false,
  "linkedRecords": [
    {
      "recordId": "rec_3n8p2w6c9r4d",
      "sourceSystemCode": "SHOP",
      "sourceRecordId": "C-58210",
      "linkType": "Auto"
    }
  ]
}
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
404 The source has no record with this ID.
Section titled “404 The source has no record with this ID.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Record not found.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Open a snapshot

Section titled “Open a snapshot”
  • Method: POST
  • Path: /api/v1/snapshots
  • Operation ID: OpenSnapshot
  • Tags: Snapshots

Starts a complete list of the source’s records. Any earlier snapshot of the source that’s still open, or held, is discarded: the newer list replaces it.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Responses

Section titled “Responses”
201 Opened.
Section titled “201 Opened.”

Content type: application/json

SnapshotResponse

The snapshot opened.

Example:

{
  "snapshotId": "3f2b8c1e-9d4a-4e7b-a1c5-6d8e2f4b9a07"
}
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
409 Rarely, a file being imported into the source in Samesake changed at the same moment. Retry the request.
Section titled “409 Rarely, a file being imported into the source in Samesake changed at the same moment. Retry the request.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "The record was changed by another request at the same time. Retry the request.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Add records to a snapshot

Section titled “Add records to a snapshot”
  • Method: POST
  • Path: /api/v1/snapshots/{snapshotId}/records
  • Operation ID: PushSnapshotRecords
  • Tags: Snapshots

Sends up to 1,000 of the source’s records to an open snapshot, as many times as you need. Each record is created or updated straight away, as by Create or update records in a batch, and counts as in the list.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Path parameters

Section titled “Path parameters”

  • snapshotId (required): string, format: uuid

    The snapshot’s ID, returned when it was opened.

    Example:

    "3f2b8c1e-9d4a-4e7b-a1c5-6d8e2f4b9a07"

Request body

Section titled “Request body”

Required: true

Content type: application/json

array of RecordInput, minItems: 1, maxItems: 1000

Example:

[
  {
    "sourceRecordId": "CRM-10042",
    "firstName": "Priya",
    "lastName": "Sharma",
    "email": "priya.sharma@example.com",
    "phones": [
      "07700 900123"
    ]
  },
  {
    "sourceRecordId": "CRM-10043",
    "title": "Mr",
    "firstName": "Tom",
    "lastName": "Fletcher",
    "dateOfBirth": "12/09/1979",
    "postcode": "M1 4BT",
    "phones": [
      "07700 900456"
    ]
  }
]

Responses

Section titled “Responses”
200 What happened to each record, in the order they were sent.
Section titled “200 What happened to each record, in the order they were sent.”

Content type: application/json

array of UpsertResult

Example:

[
  {
    "sourceRecordId": "CRM-10042",
    "recordId": "rec_7k2m9xq4ht3b",
    "outcome": "Created"
  },
  {
    "sourceRecordId": "CRM-10043",
    "recordId": "rec_3n8p2w6c9r4d",
    "outcome": "Updated"
  }
]
400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.
Section titled “400 The request isn’t valid. When a field breaks a limit, `errors` names the field and says why. A body that isn’t JSON of the right shape gets this status without `errors`.”

Content type: application/problem+json

HttpValidationProblemDetails

What went wrong, as a problem details object (RFC 9457), with errors when a field breaks a limit.

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "[1].email": [
      "email must be at most 200 characters."
    ]
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
404 The source has no snapshot with this ID.
Section titled “404 The source has no snapshot with this ID.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Snapshot not found.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
409 The snapshot isn’t open: it has been completed, or a newer snapshot replaced it. (Rarely, another request changed the same record at the same time: then retry.)
Section titled “409 The snapshot isn’t open: it has been completed, or a newer snapshot replaced it. (Rarely, another request changed the same record at the same time: then retry.)”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Snapshot is not open.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.
Section titled “413 The request body is too large: at most 64 KB for one record, 8 MB for a batch or a snapshot’s records.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.14",
  "title": "Request body is too large.",
  "status": 413,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.
Section titled “415 The body isn’t sent as JSON: set the `Content-Type` header to `application/json`.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.16",
  "title": "Unsupported Media Type",
  "status": 415,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Complete a snapshot

Section titled “Complete a snapshot”
  • Method: POST
  • Path: /api/v1/snapshots/{snapshotId}/complete
  • Operation ID: CompleteSnapshot
  • Tags: Snapshots

Says the list is complete. The source’s records that weren’t sent to the snapshot are deleted (Applied), unless that would delete more than 10% of the source’s records: then nothing is deleted and the snapshot is Held for an admin to apply or discard in Samesake. Records created or changed after the snapshot was opened, by other calls, are never deleted by it.

Servers: Inherited servers

Authentication

Section titled “Authentication”

  • ApiKey: API key in header X-Api-Key

    The source’s API key. An admin issues it in Samesake, under Admin, then Sources. Keep it secret: anyone who has it can change the source’s records.

Path parameters

Section titled “Path parameters”

  • snapshotId (required): string, format: uuid

    The snapshot’s ID, returned when it was opened.

    Example:

    "3f2b8c1e-9d4a-4e7b-a1c5-6d8e2f4b9a07"

Responses

Section titled “Responses”
200 Completed.
Section titled “200 Completed.”

Content type: application/json

SnapshotCompletionResponse

What completing the snapshot did.

Example:

{
  "status": "Applied",
  "missingCount": 3
}
401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.
Section titled “401 The `X-Api-Key` header is missing, or the key isn’t valid: it may have been revoked.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
404 The source has no snapshot with this ID.
Section titled “404 The source has no snapshot with this ID.”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Snapshot not found.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
409 The snapshot isn’t open: it has been completed, or a newer snapshot replaced it. (Rarely, another request changed the same record at the same time: then retry.)
Section titled “409 The snapshot isn’t open: it has been completed, or a newer snapshot replaced it. (Rarely, another request changed the same record at the same time: then retry.)”

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Snapshot is not open.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}
429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.
Section titled “429 Too many requests with this key: at most 600 a minute. Wait the number of seconds in the `Retry-After` header (up to 60), then retry.”

Headers:

  • Retry-After

    Seconds to wait, up to 60.

    integer

    Example:

    60

Content type: application/problem+json

ProblemDetails

What went wrong, as a problem details object (RFC 9457).

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Schemas

Section titled “Schemas”

HttpValidationProblemDetails

Section titled “HttpValidationProblemDetails”

Type: object

What went wrong, as a problem details object (RFC 9457), with errors when a field breaks a limit.

  • status (required): integer, format: int32

    The HTTP status code.

  • title (required): string

    What went wrong, in a sentence.

  • traceId (required): string

    This request’s ID. Quote it if you ask us about the error.

  • errors: object

    Each field that breaks a limit, with what’s wrong with it. In a batch, the field is named by the record’s position, counting from 0: [2].email.

    Additional properties:

    array of string

  • type: null | string

    A link to the part of the HTTP standard (RFC 9110) that defines the status. Not sent with 429.

Generated example:

{
  "type": null,
  "title": "",
  "status": 1,
  "traceId": "",
  "errors": {
    "additionalProperty": [
      ""
    ]
  }
}

LinkedRecordView

Section titled “LinkedRecordView”

Type: object

A record matched to another.

  • linkType (required): string, possible values: "Auto", "Confirmed"

    Auto: Samesake matched the records itself. Confirmed: a reviewer confirmed the match.

  • recordId (required): string

    Samesake’s ID for the record.

  • sourceRecordId (required): string

    The source’s own ID for the record.

  • sourceSystemCode (required): string

    The code of the record’s source.

Generated example:

{
  "recordId": "rec_3n8p2w6c9r4d",
  "sourceSystemCode": "SHOP",
  "sourceRecordId": "C-58210",
  "linkType": "Auto"
}

LinkType

Section titled “LinkType”

Type: string, possible values: "Auto", "Confirmed"

Auto: Samesake matched the records itself. Confirmed: a reviewer confirmed the match.

ProblemDetails

Section titled “ProblemDetails”

Type: object

What went wrong, as a problem details object (RFC 9457).

  • status (required): integer, format: int32

    The HTTP status code.

  • title (required): string

    What went wrong, in a sentence.

  • traceId (required): string

    This request’s ID. Quote it if you ask us about the error.

  • type: null | string

    A link to the part of the HTTP standard (RFC 9110) that defines the status. Not sent with 429.

Generated example:

{
  "type": null,
  "title": "",
  "status": 1,
  "traceId": ""
}

RecordIdResponse

Section titled “RecordIdResponse”

Type: object

The record written.

  • recordId (required): string

    Samesake’s ID for the record. It never changes, so you can store it beside your own.

Generated example:

{
  "recordId": ""
}

RecordInput

Section titled “RecordInput”

Type: object

A record as your system holds it. Every field except sourceRecordId is optional, and each request sends the whole record: a field left out or sent as null is cleared. Values aren’t rejected for being badly formed: a date, phone number or postcode Samesake can’t read is kept as sent, but not used for matching.

  • sourceRecordId (required): string, minLength: 1, maxLength: 100

    Your ID for the record in this source, such as a contact ID. Required, and not blank. Sending a record with the same ID again updates it. Spaces at either end are ignored.

  • addressLine1: null | string, maxLength: 200

    First line of the address, such as the house number and street.

  • addressLine2: null | string, maxLength: 200

    Second line of the address, such as the town.

  • dateOfBirth: null | string, maxLength: 200

    Date of birth, best as yyyy-mm-dd. Day-first forms such as dd/mm/yyyy, dd-mm-yyyy and dd.mm.yyyy are read too: 03/04/1986 is 3 April.

  • email: null | string, maxLength: 200

    Email address.

  • firstName: null | string, maxLength: 200

    First name.

  • lastName: null | string, maxLength: 200

    Last name.

  • phones: null | array, maxItems: 10

    Phone numbers, mobile or landline, in any usual format: 07700 900123, +44 7700 900123, (0161) 496 0123, +49 30 1234567. A number without a country code is read as belonging to the country chosen when your Samesake account was set up (usually the United Kingdom), so the same digits under two different country codes are two different numbers.

    Items:

    string, maxLength: 200

  • postcode: null | string, maxLength: 200

    UK postcode, with or without the space.

  • title: null | string, maxLength: 200

    Title, such as Mr, Mrs, Ms or Dr.

Generated example:

{
  "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"
  ]
}

RecordReplacement

Section titled “RecordReplacement”

Type: object

A record’s fields, replacing all of its current ones: a field left out or sent as null is cleared. There’s no sourceRecordId, because the path names the record (one sent anyway is ignored). Values aren’t rejected for being badly formed: a date, phone number or postcode Samesake can’t read is kept as sent, but not used for matching.

  • addressLine1: null | string, maxLength: 200

    First line of the address, such as the house number and street.

  • addressLine2: null | string, maxLength: 200

    Second line of the address, such as the town.

  • dateOfBirth: null | string, maxLength: 200

    Date of birth, best as yyyy-mm-dd. Day-first forms such as dd/mm/yyyy, dd-mm-yyyy and dd.mm.yyyy are read too: 03/04/1986 is 3 April.

  • email: null | string, maxLength: 200

    Email address.

  • firstName: null | string, maxLength: 200

    First name.

  • lastName: null | string, maxLength: 200

    Last name.

  • phones: null | array, maxItems: 10

    Phone numbers, mobile or landline, in any usual format: 07700 900123, +44 7700 900123, (0161) 496 0123, +49 30 1234567. A number without a country code is read as belonging to the country chosen when your Samesake account was set up (usually the United Kingdom), so the same digits under two different country codes are two different numbers.

    Items:

    string, maxLength: 200

  • postcode: null | string, maxLength: 200

    UK postcode, with or without the space.

  • title: null | string, maxLength: 200

    Title, such as Mr, Mrs, Ms or Dr.

Generated example:

{
  "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"
  ]
}

RecordView

Section titled “RecordView”

Type: object

A record as Samesake holds it: its details as the source sent them (all cleared once it’s deleted), the person it belongs to, and the records matched to it.

  • addressLine1 (required): null | string

    First line of the address.

  • addressLine2 (required): null | string

    Second line of the address.

  • dateOfBirth (required): null | string

    Date of birth, as sent.

  • deleted (required): boolean

    Whether the record has been deleted. A deleted record’s details are removed; its IDs stay.

  • email (required): null | string

    Email address.

  • firstName (required): null | string

    First name.

  • lastName (required): null | string

    Last name.

  • linkedRecords (required): array of LinkedRecordView

    The records matched to this one, from any source: their IDs, not their details.

  • personId (required): null | string

    Samesake’s ID for the person the record belongs to: every record matched to the same person has the same one. Null until the record has been matched. It changes if people are merged or split.

  • phones (required): array of string

    Phone numbers, as sent.

  • postcode (required): null | string

    Postcode, as sent.

  • recordId (required): string

    Samesake’s ID for the record. It never changes.

  • sourceRecordId (required): string

    Your ID for the record in its source.

  • sourceSystemCode (required): string

    The code of the record’s source.

  • title (required): null | string

    Title.

Generated example:

{
  "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": "per_5d9h2k7m3x8q",
  "deleted": true,
  "linkedRecords": [
    {
      "recordId": "rec_3n8p2w6c9r4d",
      "sourceSystemCode": "SHOP",
      "sourceRecordId": "C-58210",
      "linkType": "Auto"
    }
  ]
}

SnapshotCompletionResponse

Section titled “SnapshotCompletionResponse”

Type: object

What completing the snapshot did.

  • missingCount (required): integer, format: int32

    How many of the source’s records weren’t in the snapshot.

  • status (required): string, possible values: "Applied", "Held"

    Applied if the missing records were deleted; Held if there were too many to delete without an admin’s say-so.

Generated example:

{
  "status": "Applied",
  "missingCount": 1
}

SnapshotResponse

Section titled “SnapshotResponse”

Type: object

The snapshot opened.

  • snapshotId (required): string, format: uuid

    The snapshot’s ID, for adding records to it and completing it.

Generated example:

{
  "snapshotId": ""
}

SnapshotStatus

Section titled “SnapshotStatus”

Type: string, possible values: "Applied", "Held"

What completing a snapshot did. Applied: the records missing from it were deleted. Held: it would delete more than 10% of the source’s records, so nothing is deleted unless an admin applies it in Samesake.

UpsertOutcome

Section titled “UpsertOutcome”

Type: string, possible values: "Created", "Updated", "Unchanged"

Created: the source had no record with this ID. Updated: the record’s details changed, or a deleted record was restored. Unchanged: the record already had these details.

UpsertResult

Section titled “UpsertResult”

Type: object

What happened to one record.

  • outcome (required): string, possible values: "Created", "Updated", "Unchanged"

    Created: the source had no record with this ID. Updated: the record’s details changed, or a deleted record was restored. Unchanged: the record already had these details.

  • recordId (required): string

    Samesake’s ID for the record. It never changes.

  • sourceRecordId (required): string

    Your ID for the record, as sent (without spaces at either end).

Generated example:

{
  "sourceRecordId": "CRM-10042",
  "recordId": "rec_7k2m9xq4ht3b",
  "outcome": "Created"
}