Skip to content

notice-types.md

Latest commit

 

History

History
111 lines (85 loc) · 4.84 KB

notice-types.md

File metadata and controls

111 lines (85 loc) · 4.84 KB

Notice Type Taxonomy

Every UGCS code in the registry, grouped by correspondence domain. Payload field references point to the TypeScript interface in src/types/payload.ts.

Naming Convention

UGCS codes follow {DOMAIN}-{SUBDOMAIN}-{NNN}:

  • DOMAIN — short code for the correspondence domain (e.g. UI for Unemployment Insurance, TAX-FED for Federal Tax, WC for Workers Compensation).
  • SUBDOMAIN — optional qualifier when a domain needs subcategories (RATE, CLAIM, BILL, AUDIT, etc.).
  • NNN — zero-padded sequence number, starting at 001.

Codes are never renamed or recycled. If a notice type is deprecated, its code stays in the registry marked deprecated; a new notice type gets a fresh number. This is what keeps downstream systems from breaking on schema evolution.

Unemployment Insurance

UGCS Code Payload Typical Agencies
UI-RATE-001 SuiRateNoticePayload State UI agencies
UI-CLAIM-001 SuiMonetaryDetermPayload State UI agencies
UI-CHARGE-001 SuiChargebackPayload State UI agencies
UI-OVERPAY-001 SuiOverpaymentPayload State UI agencies
UI-APPEAL-001 SuiAppealPayload State UI agencies

Federal Tax (IRS)

UGCS Code Payload Notice Numbers
TAX-FED-BILL-001 IrsBalanceDuePayload CP14, CP501, CP503, CP504, CP504B
TAX-FED-AUDIT-001 IrsUnderreporterPayload CP2000, CP2501
TAX-FED-LEVY-001 IrsFinalLevyNoticePayload CP90, CP91, LT11, Letter 1058
TAX-FED-ACA-001 IrsAcaPenaltyPayload Letter 226J, 972CG, 5699
TAX-FED-LOCK-001 IrsLockInLetterPayload Letter 2800C, 2801C
TAX-FED-LIEN-001 IrsFederalTaxLienPayload NFTL, Letter 3172
TAX-FED-AUDIT-002 IrsAuditPayload Letter 2205, 3572, 566

State Tax

UGCS Code Payload
TAX-STATE-BILL-001 StateTaxBillingPayload
TAX-STATE-WHLD-001 StateTaxWithholdingPayload
TAX-STATE-SALES-001 StateTaxSalesPayload
TAX-STATE-ASSESS-001 StateTaxAssessmentPayload
TAX-STATE-AUDIT-001 StateTaxAuditPayload
TAX-STATE-LIEN-001 StateTaxLienPayload

Workers Compensation

UGCS Code Payload
WC-PREM-001 WcPremiumInvoicePayload
WC-RATE-001 WcExperienceRatingPayload
WC-AUDIT-001 WcPayrollAuditPayload
WC-CLAIM-001 WcClaimNotificationPayload
WC-COMP-001 WcCoverageLapsePayload

Federal Labor

UGCS Code Payload
LABOR-FED-OSHA-001 OshaCitationPayload
LABOR-FED-EEOC-001 EeocChargePayload
LABOR-FED-WHD-001 DolWageHourPayload

Immigration / Identity

UGCS Code Payload
IMM-I9-001 I9AuditPayload
IMM-EVERIFY-001 EverifyTncPayload
IMM-SSA-001 SsaNoMatchPayload

State Disability

UGCS Code Payload
DIS-RATE-001 StateDisabilityRatePayload
DIS-DELIN-001 StateDisabilityDelinqPayload

Entity / Compliance

UGCS Code Payload
ENTITY-SOS-001 SosAnnualReportPayload
ENTITY-SOS-002 SosRegisteredAgentPayload

Licensing

UGCS Code Payload
LIC-BUS-001 BusinessLicensePayload

Generic Fallback

UGCS Code Payload
GENERIC-001 GenericNoticePayload

Use this when a notice doesn't fit any known type. Set requires_human_review: true and explain why in reason_for_fallback. The goal is not to force every notice into an existing bucket — it's to have a clean escape hatch that routes ambiguous cases to humans.