Customer Master Record Creation and Deduplication

A new customer record is initiated by a sales rep post-opportunity-close or by an onboarding specialist. The system checks for existing accounts by company name, domain, tax ID, and phone to surface potential duplicates for manual review. The rep confirms uniqueness or merges into an existing record. The confirmed account record is enriched with data from a configured third-party enrichment provider (e.g., Clearbit, ZoomInfo) and synced to the billing system. A unique external ID anchors the record across ERP, CRM, and billing systems.

customer { id: string (cust_*), external_id: string, legal_name: string, domain: string, tax_id: string, billing_address_id: string, primary_contact_id: string, currency_code: char(3), payment_terms: string, parent_account_id: string, gdpr_flag: bool, status: enum(ACTIVE, INACTIVE), created_at: timestamp };
dedup_candidate { id, source_id, match_score, matched_fields: array };
(reference, product may differ).

POST /v1/customers { external_id, legal_name, domain, tax_id, billing_address, primary_contact, currency_code, payment_terms } -> 201 { id, dedup_candidates: [] };
POST /v1/customers/{id}/merge { surviving_id } -> 200;
GET /v1/customers/{id};
emits customer.created, customer.merged, customer.enriched events;
idempotent via external_id.

PENDING_DEDUP -> ACTIVE | MERGED;
terminal INACTIVE, MERGED;
guard: ACTIVE requires all mandatory fields populated;
MERGED preserves history on surviving record;
INACTIVE blocks new orders;
external_id immutable after creation.