> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity Resolution

> Resolve, link, and merge customer identities across channels and systems.

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

| Parameter    | Type   | Required | Description            |
| ------------ | ------ | -------- | ---------------------- |
| `customerId` | string | Yes      | Customer ID to look up |

### Example

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

### Response

```json theme={null}
{
  "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

```json theme={null}
{
  "action": "resolve",
  "identifier": { "type": "email", "value": "john@example.com" }
}
```

**Response:**

```json theme={null}
{ "canonicalId": "C-1234" }
```

#### `link` — Link identifiers to a canonical ID

```json theme={null}
{
  "action": "link",
  "canonicalId": "C-1234",
  "identifiers": [
    { "type": "phone", "value": "+1-555-0100" },
    { "type": "device_id", "value": "dev_abc123" }
  ],
  "confidence": 0.9
}
```

**Response:**

```json theme={null}
{ "success": true }
```

#### `merge` — Merge two identity clusters

Merges all identifiers from `sourceId` into `targetId`.

```json theme={null}
{
  "action": "merge",
  "targetId": "C-1234",
  "sourceId": "C-5678"
}
```

**Response:**

```json theme={null}
{ "success": true }
```