Identity Resolution

The Patient Graph supports cross-system identity mapping to link a single patient across multiple external systems (Clerk, Rimo Health, BigCommerce, etc.).

How It Works

The identity_mappings table stores relationships between a Patient Graph customerId and external system identifiers:

customer_profiles.id ──→ identity_mappings
                          ├── clerk: user_clerk_123
                          ├── rimo: rimo_patient_456
                          ├── bigcommerce: bc_customer_789
                          └── stripe: cus_abc123

Creating Mappings

import { resolveIdentity } from '@loop/patient-graph';
 
// Resolve or create a mapping
const customerId = await resolveIdentity({
  externalSystem: 'rimo',
  externalId: 'rimo_patient_456',
  fallbackData: {
    email: 'patient@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
  },
});

If a mapping already exists, the existing customerId is returned. If not, a new profile is created using the fallbackData and the mapping is stored.

Use Cases

Rimo Webhooks

When a Rimo webhook arrives with a rimoPatientId, the system resolves it to a Patient Graph profile:

const customerId = await resolveIdentity({
  externalSystem: 'rimo',
  externalId: event.data.patientId,
});

BigCommerce Sync

When syncing purchase data, BigCommerce customer IDs are mapped:

const customerId = await resolveIdentity({
  externalSystem: 'bigcommerce',
  externalId: bcCustomer.id.toString(),
});

Luna AI

Luna AI uses the Clerk user ID as the primary identifier. The getPatientContext() function automatically resolves identity mappings to find the patient’s profile.

Supported Systems