Bitespeed Identity Reconciliation API

This service provides an API endpoint for identifying and reconciling customer identities across multiple purchases with different contact information.

Overview

The Identity Reconciliation API helps track a customer's identity across multiple purchases by linking different contact information (email addresses and phone numbers) to the same person.

API Endpoint

POST /identify

Identifies and consolidates contact information based on the provided email and/or phone number.

Request

{
  "email": "string | null",
  "phoneNumber": "string | null"
}

At least one of email or phoneNumber must be provided.

Response

{
  "contact": {
    "primaryContactId": number,
    "emails": string[],
    "phoneNumbers": string[],
    "secondaryContactIds": number[]
  }
}

• primaryContactId: ID of the primary contact
• emails: Array of all email addresses associated with the contact (primary contact's email first)
• phoneNumbers: Array of all phone numbers associated with the contact (primary contact's phone number first)
• secondaryContactIds: Array of IDs of all secondary contacts linked to the primary contact

How It Works

1. When a request is received with an email and/or phone number, the service searches for existing contacts with matching information.
2. If no matching contacts are found, a new primary contact is created.
3. If matching contacts are found, the service identifies the primary contact and consolidates all related contact information.
4. If the request contains new information (email or phone number) that doesn't exist in the contact network, a new secondary contact is created and linked to the primary contact.
5. If multiple primary contacts are found to be related, the oldest one is kept as primary and the others are converted to secondary.

Running the Application

Prerequisites

• Node.js (v14 or higher)
• npm or yarn

Installation

1. Clone the repository

   git clone <repository-url>
   cd identity-reconciliation
   

2. Install dependencies

   npm install
   

3. Start the development server

   npm run dev
   

Production

1. Build the application

   npm run build
   

2. Start the production server

   npm start
   

Database Schema

The service uses a SQLite database with a single table:

Contact {
  id                   Int                   
  phoneNumber          String?
  email                String?
  linkedId             Int?  // the ID of another Contact linked to this one
  linkPrecedence       "secondary"|"primary"  // "primary" if it's the first Contact in the link
  createdAt            DateTime              
  updatedAt            DateTime              
  deletedAt            DateTime?
}

License

ISC