Investigation Engine Input Schema

Minimum viable dataset for Tier 1. payment_date, payment_amount, payment_currency, payment_id, payment_type, payee_type, full_name OR entity_legal_name, at least one identifier (ssn_last4, ein, npi, or bank_account_number), payee_address_line1, payee_city, payee_state, lookback_start_date, lookback_end_date, check_tier.

Section A - Payment Record

Field	Type	Status	Unlocks
`payment_date`	ISO date	REQUIRED	All temporal checks - this is the anchor date
`payment_amount`	decimal string	REQUIRED	Capacity plausibility, exposure calculation
`payment_currency`	ISO 4217	REQUIRED	Exposure normalization
`payment_id`	string	REQUIRED	Links findings to source records
`payment_type`	enum	REQUIRED	medicare_claim, medicaid_claim, ssa_benefit, federal_vendor, payroll, insurance_claim, childcare_subsidy, va_benefit, snap, unemployment, other
`payment_rail`	enum	Optional	ach, wire, check, fedwire, rtp, fednow, swift
`program_id`	string	Conditional	Medicare beneficiary ID, SSA claim number, Medicaid case number, contract number

Section B - Person Identity

Field	Type	Status	Unlocks
`payee_type`	enum	REQUIRED	"individual" or "entity"
`full_name`	string	REQUIRED	DMF match, license lookup, sanctions
`date_of_birth`	ISO date	Conditional	Required for DMF day-precision match
`ssn_last4`	string	Optional	DMF confidence, SSA NUMIDENT. Last 4 only; never full SSN.
`gender`	string	Optional	Disambiguates DMF matches on common names
`marital_status_claimed`	string	Conditional	Required for spousal benefit checks
`spouse_name`	string	Conditional	Marriage certificate cross-reference
`spouse_date_of_death`	ISO date	Conditional	Survivor benefit eligibility onset
`citizenship_claimed`	string	Conditional	DHS SAVE eligibility, program eligibility
`country_of_birth`	ISO 3166-1	Optional	Routes citizenship check

Section C - Entity Identity

Field	Type	Status	Unlocks
`entity_legal_name`	string	REQUIRED	SOS lookup, DUNS match, IRS TIN
`ein`	string	Conditional	IRS TIN match (ID-015), entity existence
`duns_number`	string	Optional	D&B match, SAM.gov cross-reference
`uei`	string	Optional	SAM.gov debarment (ID-004), federal vendor checks
`state_of_incorporation`	US state	Conditional	Routes SOS dissolution check (ID-005, ID-006)
`state_of_operation`	US state	Conditional	Business license check, cross-state shell flag
`business_license_number`	string	Optional	Business license expiration/revocation (ID-007, ID-008)
`npi`	string	Conditional	NPI active (ID-011), PECOS (ID-012), OIG LEIE
`taxonomy_code`	string	Optional	Taxonomy match vs. billed service type
`lei`	string	Optional	GLEIF registry, trust score boost

Section D - Professional Credentials

Field	Type	Status	Unlocks
`license_type`	enum	Conditional	Professional license check (ID-012)
`license_number`	string	Optional	Exact license record match
`license_state`	US state	Conditional	Routes to state licensing board
`dea_number`	string	Optional	DEA registration status (ID-014)
`finra_crd`	string	Optional	BrokerCheck registration and disciplinary history

Section E - Address

Field	Type	Status	Unlocks
`payee_address_line1`	string	REQUIRED	Address verification, classification, occupancy
`payee_address_line2`	string	Optional	Multi-registrant density
`payee_city`	string	REQUIRED	Geographic plausibility
`payee_state`	US state	REQUIRED	Licensing board routing, SOS routing, service area
`payee_zip`	string	Conditional	USPS NCOA tenure check (ID-019)
`address_type_claimed`	string	Optional	Comparison against JIL classification
`service_address`	object	Conditional	Home health/hospice patient address for service area plausibility

Section F - Bank Account

Field	Type	Status	Unlocks
`bank_account_number`	string	REQUIRED	Bank account age and tenure check. Masked last-4 accepted.
`bank_routing_number`	string	REQUIRED	Bank existence and routing validity
`account_type`	enum	Optional	Account type vs. payee type mismatch flag
`account_open_date`	ISO date	Optional	Account age - rapid creation for fraud
`account_holder_name`	string	Optional	Holder vs. payee name mismatch = redirect flag
`account_changed_during_period`	boolean	Optional	BEC redirect flag
`account_change_date`	ISO date	Conditional	Temporal pre/post-change analysis

Section G - Marital Status and Spousal Benefits

Field	Type	Status	Unlocks
`marriage_check_requested`	boolean	Optional	State vital records marriage database
`marriage_date_claimed`	ISO date	Conditional	Confirms marriage was in place at spousal benefit start
`divorce_date_claimed`	ISO date	Conditional	Benefit termination date cross-reference
`remarriage_check`	boolean	Optional	Survivor benefits terminate on remarriage
`benefit_type`	enum	Conditional	spousal_ssa, survivor_ssa, spousal_medicare, divorced_spouse_ssa, survivor_va

Section H - Investigation Configuration

Field	Type	Status	Effect
`lookback_start_date`	ISO date	REQUIRED	Earliest payment date in the audit window
`lookback_end_date`	ISO date	REQUIRED	Latest payment date in the audit window
`check_tier`	enum	REQUIRED	"tier1", "tier2", "tier3"
`referral_package`	boolean	Optional	PDF case packages with statute references for CRITICAL findings
`ignore_log_included`	boolean	Optional	Enables departmental abuse pattern detection
`output_format`	enum	Optional	json, csv, json_and_csv - default json
`zkp_proof_requested`	boolean	Optional	Privacy-preserving evidence sharing with regulators

Investigation Engine Input Schema

Section A - Payment Record

Section B - Person Identity

Section C - Entity Identity

Section D - Professional Credentials

Section E - Address

Section F - Bank Account

Section G - Marital Status and Spousal Benefits

Section H - Investigation Configuration

Related specifications