Skip to main content
The Identity Resolution API manages customer identity graphs. It resolves multiple identifiers (email, phone, device ID) to a single canonical customer ID and supports merging identity clusters.

​
GET /api/v1/identity

Get the identity cluster for a customer — all linked identifiers and their confidence scores.

​
Query Parameters

ParameterTypeRequiredDescription
customerIdstringYesCustomer ID to look up

​
Example

curl "https://playground.kaireonai.com/api/v1/identity?customerId=C-1234" \
  -H "X-Tenant-Id: my-tenant"

​
Response

{
  "customerId": "C-1234",
  "cluster": {
    "canonicalId": "C-1234",
    "identifiers": [
      { "type": "email", "value": "john@example.com", "confidence": 1.0 },
      { "type": "phone", "value": "+1-555-0100", "confidence": 0.95 },
      { "type": "device_id", "value": "dev_abc123", "confidence": 0.8 }
    ]
  }
}

​
POST /api/v1/identity

Perform identity resolution actions. Editor or Admin.

​
Actions

​
resolve — Resolve an identifier to a canonical ID

{
  "action": "resolve",
  "identifier": { "type": "email", "value": "john@example.com" }
}
Response: 
{ "canonicalId": "C-1234" }

{
  "action": "link",
  "canonicalId": "C-1234",
  "identifiers": [
    { "type": "phone", "value": "+1-555-0100" },
    { "type": "device_id", "value": "dev_abc123" }
  ],
  "confidence": 0.9
}
Response: 
{ "success": true }

​
merge — Merge two identity clusters

Merges all identifiers from sourceId into targetId. 
{
  "action": "merge",
  "targetId": "C-1234",
  "sourceId": "C-5678"
}
Response: 
{ "success": true }