Backend Service: Identity Reconciliation

(NodeTS, REST APIs, Postgres SQL)

Authors

• Md Husain Thekiya
  • [email protected]
  • https://github.com/MdHusainThekiya/
  • https://www.linkedin.com/in/md-husain-thekiya/

Overview

This project implements a web service that helps amazon.in link different orders made with various contact information to the same customer. By using different email addresses and phone numbers for each purchase, a customer like Doc makes it challenging to track his identity. The service reconciles this information to provide a personalized customer experience.

Local Environment Setup

0. if not using docker-compose, requied node.js version 16, postgres 13
1. run following commands

1. Clone project

git clone [email protected]:MdHusainThekiya/contactIdentifierAPI.git

cd contactIdentifierAPI

2. create environment variables

To run this project, you will need to add the following environment variables to your .env file

refer .sample.env file

cp .sample.env .env
vim .env

modify .env as per your values and execute below commands

with docker

docker compose up -d

without docker

required postgresDB to be up and running

npm install
npm run build
npm start

service will be up and running on post 4040

curl http://127.0.0.1:4040/

.env contails following

# SERVICE CONFIGS
PORT=4040
ENABLE_LOGS=true
ALLOWED_LOG_LEVELS='all'
ENABLE_LOG_LOCATION=true

# PG CONFIGS
POSTGRES_URL="postgres://postgresUser:[email protected]:5432/postgresDB"
POSTGRES_HOST='0.0.0.0'
POSTGRES_PORT=5432
POSTGRES_USER=postgresUser
POSTGRES_PASSWORD=postgresPass
POSTGRES_DB_NAME=postgresDB

Usage

Once the server is running, you can use the /identify endpoint to link customer identities.

API Endpoint

POST /identify

Request Body:

{
  "email": "string?",
  "phoneNumber": "number?"
}

Response:

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

• If the contact already exists, the response will include the consolidated contact information.
• If the contact does not exist, a new entry will be created with linkPrecedence="primary".

Database Schema

The database contains a table named Contact with the following columns:

{
  "id": "Int",
  "phoneNumber": "String?",
  "email": "String?",
  "linkedId": "Int?",
  "linkPrecedence": "String", // "primary" or "secondary"
  "createdAt": "DateTime",
  "updatedAt": "DateTime",
  "deletedAt": "DateTime?"
}

• Primary Contact: The oldest contact entry with linkPrecedence="primary".
• Secondary Contact: Contacts linked to the primary contact.

Example Scenarios

Example 1:

Existing Contact:

{
  "id": 1,
  "phoneNumber": "123456",
  "email": "[email protected]",
  "linkedId": null,
  "linkPrecedence": "primary",
  "createdAt": "2023-04-01 00:00:00.374+00",
  "updatedAt": "2023-04-01 00:00:00.374+00",
  "deletedAt": null
}

New Request:

{
  "email": "[email protected]",
  "phoneNumber": "123456"
}

Database State After Request:

{
  "id": 1,
  "phoneNumber": "123456",
  "email": "[email protected]",
  "linkedId": null,
  "linkPrecedence": "primary",
  "createdAt": "2023-04-01 00:00:00.374+00",
  "updatedAt": "2023-04-01 00:00:00.374+00",
  "deletedAt": null
},
{
  "id": 23,
  "phoneNumber": "123456",
  "email": "[email protected]",
  "linkedId": 1,
  "linkPrecedence": "secondary",
  "createdAt": "2023-04-20 05:30:00.11+00",
  "updatedAt": "2023-04-20 05:30:00.11+00",
  "deletedAt": null
}

Example 2:

Request:

{
  "email": "[email protected]",
  "phoneNumber": "717171"
}

Database State After Request:

{
  "id": 11,
  "phoneNumber": "919191",
  "email": "[email protected]",
  "linkedId": null,
  "linkPrecedence": "primary",
  "createdAt": "2023-04-11 00:00:00.374+00",
  "updatedAt": "2023-04-11 00:00:00.374+00",
  "deletedAt": null
},
{
  "id": 27,
  "phoneNumber": "717171",
  "email": "[email protected]",
  "linkedId": 11,
  "linkPrecedence": "secondary",
  "createdAt": "2023-04-21 05:30:00.11+00",
  "updatedAt": "2023-04-28 06:40:00.23+00",
  "deletedAt": null
}

Hosting

The application is hosted on Vercel.com. You can access the /identify endpoint at the following URL:

curl --location 'https://contact-identifier-api.vercel.app/identify' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email" : "[email protected]",
    "phoneNumber" : null
}'