Vendor Management - Technical Specification

Healthcare vendor and provider organization management

Purpose

The Vendor Management module serves as the foundation for all healthcare provider organizations in the system. Vendors represent the business entities (medical practices, hospitals, therapy centers) that employ clinical providers and submit claims for payment. Each vendor has a Tax ID for financial transactions, can have multiple locations, employ multiple clinical providers, and maintain contracts with specific rates. The vendor entity is critical for claim validation and payment processing.

Key Concepts

Term	Definition
Vendor	Healthcare organization or practice that provides medical services
Tax ID	Federal Tax Identification Number (EIN) for the business entity
Parent Vendor	Higher-level organization that owns subsidiary vendors
Vendor Type	Category of healthcare provider (Hospital, Clinic, Therapy, Imaging, etc.)
W9 Form	IRS form with vendor tax information
Provider Roster	List of clinical providers employed by vendor
Vendor Location	Physical service delivery sites
Vendor Contract	Agreement defining rates and terms
Billing Entity	Entity that submits claims (may differ from service location)
Vendor Status	Active, Inactive, Suspended, Pending

User Roles

Role	Description	Permissions
Provider Relations Manager	Manages vendor relationships	Full CRUD
Contract Manager	Handles vendor contracts	Read, Update contracts
Credentialing Specialist	Verifies vendor credentials	Read, Update documents
Claims Processor	Uses vendor data for claims	Read only
Financial Analyst	Reviews vendor payments	Read, Reports
System Administrator	System configuration	All permissions

Field Documentation - Vendor Entity

Field Name	Type	Required	Description	Validation Rules	Related Entity
ID	String	Yes	Unique vendor identifier	Auto-generated CUID	Primary Key
Vendor Name	String	Yes	Legal business name	Max 200 chars	-
DBA Name	String	No	Doing Business As name	Max 200 chars	-
Tax ID	String	Yes	Federal EIN	Format: XX-XXXXXXX, unique	-
Tax ID Type	String	Yes	Type of Tax ID	Enum: EIN, SSN	-
Vendor Type	String	Yes	Category of provider	Enum: Hospital, Clinic, Therapy, Imaging, Lab, DME, Other	-
Vendor Sub Type	String	No	Specific vendor category	Based on vendor type	-
Parent Vendor	Vendor	No	Parent organization	Must be active vendor	Vendor
NPI Organization	String	No	Organization NPI (Type 2)	10-digit NPI validation	-
Business Address	String	Yes	Primary business address	Valid street address	-
Business City	String	Yes	Business city	Max 100 chars	-
Business State	String	Yes	Business state	2-letter state code	-
Business Zip	String	Yes	Business ZIP code	5 or 9 digits	-
Mailing Address	String	No	Mailing address if different	Valid street address	-
Mailing City	String	No	Mailing city	Max 100 chars	-
Mailing State	String	No	Mailing state	2-letter state code	-
Mailing Zip	String	No	Mailing ZIP	5 or 9 digits	-
Phone	String	Yes	Primary phone	10 digits	-
Fax	String	No	Fax number	10 digits	-
Email	String	Yes	Primary contact email	Valid email format	-
Website	String	No	Vendor website	Valid URL format	-
Contact Name	String	Yes	Primary contact person	Max 200 chars	-
Contact Title	String	No	Contact person's title	Max 100 chars	-
Contact Phone	String	Yes	Contact phone	10 digits	-
Contact Email	String	Yes	Contact email	Valid email format	-
Billing Contact	String	No	Billing department contact	Max 200 chars	-
Billing Email	String	No	Billing email	Valid email format	-
Billing Phone	String	No	Billing phone	10 digits	-
Payment Terms	String	No	Payment terms	Enum: Net30, Net45, Net60	-
Vendor Status	String	Yes	Current status	Enum: Active, Inactive, Suspended, Pending	-
Status Reason	String	No	Reason for status	Required if not Active	-
Effective Date	DateTime	Yes	Vendor start date	Cannot be future	-
Termination Date	DateTime	No	Vendor end date	Must be after effective date	-
W9 On File	Boolean	Yes	W9 form received	Default false	-
W9 Date	DateTime	No	Date W9 received	Required if W9 on file	-
W9 Document	Document	No	W9 form file	PDF format	Document
Business License Number	String	No	State business license	Alphanumeric	-
Business License Expiry	DateTime	No	License expiration	Must be future if active	-
Liability Insurance	Boolean	Yes	Has liability insurance	Default false	-
Insurance Expiry	DateTime	No	Insurance expiration	Required if insured	-
Insurance Amount	Decimal	No	Coverage amount	Positive number	-
Accreditation	String	No	Accreditation body	Free text	-
Accreditation Expiry	DateTime	No	Accreditation expiration	Future date if active	-
Business Central ID	String	No	BC vendor number	From BC sync	-
Created At	DateTime	Yes	Creation timestamp	Auto-generated	-
Updated At	DateTime	Yes	Update timestamp	Auto-updated	-
Created By	User	Yes	Creating user	Valid user ID	User
Updated By	User	Yes	Updating user	Valid user ID	User
Clinical Providers	ClinicalProvider[]	No	Employed providers	-	ClinicalProvider (1:Many)
Locations	VendorLocation[]	No	Service locations	-	VendorLocation (1:Many)
Contracts	Contract[]	No	Vendor contracts	-	Contract (1:Many)
Documents	Document[]	No	Vendor documents	-	Document (1:Many)

Field Documentation - Vendor Location Entity

Field Name	Type	Required	Description	Validation Rules	Related Entity
ID	String	Yes	Unique location ID	Auto-generated	Primary Key
Vendor	Vendor	Yes	Parent vendor	Must be active	Vendor
Location Name	String	Yes	Location identifier	Max 200 chars	-
Location Type	String	Yes	Type of location	Enum: Main, Branch, Satellite	-
NPI Location	String	No	Location-specific NPI	10-digit NPI	-
Address	String	Yes	Street address	Valid address	-
City	String	Yes	City	Max 100 chars	-
State	String	Yes	State	2-letter code	-
Zip Code	String	Yes	ZIP code	5 or 9 digits	-
Phone	String	Yes	Location phone	10 digits	-
Fax	String	No	Location fax	10 digits	-
Hours of Operation	Text	No	Business hours	JSON format	-
Is Primary	Boolean	Yes	Primary location flag	One per vendor	-
Is Billing Location	Boolean	Yes	Bills from here	Default false	-
Active	Boolean	Yes	Location active	Default true	-

Workflows

Vendor Onboarding Workflow

1. Initial Registration

   • Collect business information
   • Verify Tax ID uniqueness
   • Check for parent vendor relationship
   • Set initial status to "Pending"

2. Document Collection

   • Request W9 form
   • Collect business license
   • Verify liability insurance
   • Provider roster submission

3. Verification Process

   • Validate Tax ID with IRS
   • Verify business license
   • Confirm insurance coverage
   • Check accreditation status

4. Location Setup

   • Add primary location
   • Configure additional locations
   • Set billing location
   • Verify addresses

5. Provider Assignment

   • Link clinical providers
   • Verify provider NPIs
   • Update provider rosters
   • Set provider-location relationships

6. Contract Negotiation

   • Create contract record
   • Define rate structures
   • Set contract terms
   • Approval workflow

7. Activation

   • Final review
   • Set status to "Active"
   • Enable for claim submission
   • Sync to Business Central

Vendor Maintenance Workflow

1. Information Updates

   • Log change request
   • Validate changes
   • Update records
   • Audit trail creation

2. Document Renewal

   • Track expiration dates
   • Send renewal notices
   • Update documents
   • Maintain compliance

3. Status Management

   • Review vendor performance
   • Handle suspensions
   • Reactivation process
   • Termination procedures

Business Rules

Registration Rules

• Tax ID must be unique in system
• W9 required before first payment
• At least one location required
• Primary contact required
• Business license required for activation

Hierarchy Rules

• Vendor can have one parent vendor
• Parent vendor must be active
• Circular references prevented
• Child vendors inherit some parent settings

Location Rules

• One primary location per vendor
• At least one billing location
• Locations must have unique addresses
• Active vendors need active locations

Provider Rules

• Providers can work at multiple vendors
• Provider must be credentialed
• NPI must be valid
• Specialty must match vendor type

Integrations

System	Integration Type	Purpose
Clinical Provider Management	Direct Database	Provider employment
Contract Management	Direct Database	Rate agreements
Claims Processing	Direct Database	Claim validation
Business Central	API Sync	Vendor master sync
Document Management	File System	W9 and document storage
NPI Registry	External API	NPI validation
IRS TIN Match	External API	Tax ID verification

Common Issues

Issue	Description	Resolution
Duplicate Tax ID	Same Tax ID submitted	Check for existing vendor
Invalid NPI	Organization NPI fails check	Verify with NPI registry
Expired Documents	W9, insurance expired	Renewal workflow
No Active Location	All locations inactive	Reactivate or add location
Parent Vendor Inactive	Parent vendor suspended	Review hierarchy impact

Screenshots Needed

• Vendor Registration Form
• Vendor Search Interface
• Vendor Profile View
• Location Management Grid
• Provider Assignment Interface
• Document Upload Section
• Contract List View
• Vendor Hierarchy Tree
• Status Change Dialog
• W9 Tracking Report

Performance Considerations

• Tax ID lookup must be indexed
• Support 10,000+ vendor records
• Location search optimization
• Document storage scalability
• Real-time sync with Business Central

Security Considerations

• Tax ID encryption at rest
• W9 document access control
• Audit trail for all changes
• Role-based vendor access
• PII protection compliance

Notes

• Vendors cannot be deleted, only inactivated
• All vendor changes are audited
• W9 forms must be updated every 3 years
• Integration with vendor credentialing services planned