n8n-nodes-officeally

[Velocity BPA Licensing Notice]

This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).

Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.

For licensing information, visit https://velobpa.com/licensing or contact [email protected].

A comprehensive n8n community node for Office Ally healthcare clearinghouse integration, providing 24 resources and 200+ operations for eligibility verification, claims management, ERA processing, patient management, scheduling, payment posting, and revenue cycle management.

Features

• Real-Time Eligibility Verification - Submit 270 inquiries and parse 271 responses for instant insurance verification
• Professional Claims (837P) - Build and submit professional healthcare claims with full validation
• Institutional Claims (837I) - Support for facility/hospital claim submission
• Claim Status Inquiry (276/277) - Check claim status and track submissions through the clearinghouse
• Electronic Remittance (835/ERA) - Retrieve and parse ERA files for payment posting
• Patient Management - Full CRUD operations for patient demographics and insurance
• Provider Management - Manage rendering and billing providers with NPI validation
• Appointment Scheduling - Create, update, and manage patient appointments
• Charge Entry - Record services and manage unbilled charges
• Payment Posting - Post payments and manage remittance application
• Statement Generation - Generate and send patient statements
• Denial Management - Track denials, appeals, and analyze denial trends
• SFTP Integration - Batch file transfers for large-scale processing
• EDI Operations - Direct EDI file handling with validation
• Comprehensive Code Lookups - CPT, ICD-10, HCPCS, CARC, RARC, POS codes

Installation

Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Click Install
4. Enter n8n-nodes-officeally
5. Accept the risks and click Install
6. Restart n8n

Manual Installation

# Navigate to your n8n installation directory
cd ~/.n8n

# Install the package
npm install n8n-nodes-officeally

Development Installation

# Clone or extract the package
cd n8n-nodes-officeally

# Install dependencies
npm install

# Build the project
npm run build

# Link to n8n custom nodes directory
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-officeally

# Restart n8n

Credentials Setup

Office Ally API Credentials

| Field | Description | Required | |-------|-------------|----------| | Environment | Production, Test, or Custom | Yes | | Username | Office Ally username | Yes | | Password | Office Ally password | Yes | | Practice ID | Your practice identifier | Yes | | Vendor Key | Vendor API key (if applicable) | No | | API Key | Additional API key | No | | Service Type | API or Portal | Yes |

Office Ally Portal Credentials

| Field | Description | Required | |-------|-------------|----------| | Portal Username | Portal login username | Yes | | Portal Password | Portal login password | Yes | | Practice ID | Practice identifier | Yes | | Two-Factor Auth | Enable 2FA support | No | | Security Question 1 | First security question | If 2FA | | Security Answer 1 | First security answer | If 2FA | | Security Question 2 | Second security question | If 2FA | | Security Answer 2 | Second security answer | If 2FA |

Office Ally SFTP Credentials

| Field | Description | Required | |-------|-------------|----------| | Host | SFTP server hostname | Yes | | Port | SFTP port (default: 22) | Yes | | Username | SFTP username | Yes | | Password | SFTP password | If not using key | | Private Key | SSH private key | If not using password | | Passphrase | Key passphrase | If key is encrypted | | Upload Directory | Default upload path | No | | Download Directory | Default download path | No | | Connection Timeout | Timeout in seconds | No |

Resources & Operations

Eligibility Resource (270/271)

• Check Eligibility - Submit real-time eligibility inquiry
• Batch Check - Submit multiple eligibility requests
• Get Response - Retrieve eligibility response
• Get Benefits - Get detailed benefit information
• Get Coverage - Get coverage summary
• Get Deductible - Get deductible information
• Get Copay - Get copay information
• Get Prior Auth - Get prior authorization requirements
• Get History - Get eligibility history
• Parse 271 - Parse 271 EDI response

Claim Resource (837)

• Create - Create new claim
• Submit - Submit claim for processing
• Submit Professional - Submit 837P claim
• Submit Institutional - Submit 837I claim
• Get - Get claim by ID
• Get All - List claims with filters
• Update - Update claim details
• Delete - Delete claim
• Get Status - Get claim status
• Resubmit - Resubmit claim
• Correct - Submit corrected claim (frequency code 7)
• Void - Void claim (frequency code 8)
• Copy - Copy claim as template

Claim Status Resource (276/277)

• Check - Submit claim status inquiry
• Get Response - Get status response
• By Claim ID - Get status for specific claim
• By Patient - Get statuses by patient
• By Date Range - Get statuses by date range
• Parse 277 - Parse 277 EDI response

Remittance Resource (835/ERA)

• Get ERA - Get specific ERA
• List ERAs - List ERAs with filters
• By Check - Get ERA by check number
• By Date - Get ERAs by date range
• By Payer - Get ERAs by payer
• Parse 835 - Parse 835 EDI file
• Get Payments - Get payment details
• Get Adjustments - Get adjustment details
• Get Denials - Get denial information
• Download File - Download ERA file
• Get Summary - Get ERA summary

Patient Resource

• Create - Create patient
• Get - Get patient by ID
• Update - Update patient
• Search - Search patients
• Get Demographics - Get demographics
• Get Insurance - Get insurance info
• Get Claims - Get patient claims
• Get History - Get patient history
• Merge - Merge duplicate patients

Provider Resource

• Create - Create provider
• Get - Get provider by ID
• Update - Update provider
• List - List all providers
• By NPI - Get provider by NPI
• Validate NPI - Validate NPI number
• Get Credentials - Get provider credentials

Payer Resource

• List - List all payers
• Get Info - Get payer information
• By ID - Get payer by ID
• Search - Search payers
• Get Rules - Get payer rules
• Get Requirements - Get submission requirements
• Check Connectivity - Test payer connection

Insurance Resource

• Add - Add insurance to patient
• Get - Get insurance details
• Update - Update insurance
• Delete - Delete insurance
• By Patient - Get patient insurances
• Verify - Verify insurance
• Get Primary - Get primary insurance
• Get Secondary - Get secondary insurance

Appointment Resource

• Create - Create appointment
• Get - Get appointment
• Update - Update appointment
• Delete - Delete appointment
• List - List appointments
• By Date - Get by date
• By Patient - Get by patient
• By Provider - Get by provider
• Check In - Check in patient
• Check Out - Check out patient

Scheduler Resource

• Get Schedule - Get practice schedule
• Get Provider Schedule - Get provider schedule
• Get Slots - Get available slots
• Block Time - Block time slot
• Unblock Time - Unblock time slot
• Get Template - Get schedule template

Charge Resource

• Create - Create charge
• Get - Get charge
• Update - Update charge
• Delete - Delete charge
• By Patient - Get by patient
• By Date - Get by date
• Get Unbilled - Get unbilled charges
• Batch Create - Create multiple charges

Payment Resource

• Post - Post payment
• Get - Get payment
• List - List payments
• By Patient - Get by patient
• By Payer - Get by payer
• By Date - Get by date range
• Apply - Apply to claim
• Get Unapplied - Get unapplied payments
• Reverse - Reverse payment
• Get History - Get payment history

Statement Resource

• Generate - Generate statement
• Get - Get statement
• Send - Send to patient
• List - List statements
• Get PDF - Download PDF
• Batch Generate - Generate multiple
• Get Queue - Get statement queue

Report Resource

• Generate - Generate report
• Get - Get report
• List - List reports
• Get Aging - A/R aging report
• Get Payment - Payment report
• Get Production - Production report
• Get Denial - Denial report
• Get Financial - Financial summary
• Export - Export report

Document Resource

• Upload - Upload document
• Get - Get document
• List - List documents
• Delete - Delete document
• By Patient - Get by patient
• Get Types - Get document types

Batch Resource

• Submit - Submit batch
• Get Status - Get batch status
• Get Results - Get batch results
• List - List batches
• Get Errors - Get batch errors
• Cancel - Cancel batch
• Download - Download response

EDI Resource

• Submit - Submit EDI file
• Get Response - Get EDI response
• Get Acknowledgment - Get 997/999
• Parse - Parse EDI file
• Generate - Generate EDI
• Validate - Validate EDI
• Get History - Get EDI history

Clearinghouse Resource

• Get Status - Get clearinghouse status
• Get Enrolled - Get enrolled payers
• Get Connection - Get connection status
• Test Connection - Test payer connection
• Get Enrollment - Get enrollment info

Enrollment Resource

• Start - Start enrollment
• Get Status - Get enrollment status
• Complete - Complete enrollment
• Get Requirements - Get requirements
• Get Payers - Get enrolled payers
• Update - Update enrollment

Denial Management Resource

• Get Denials - Get all denials
• Get Details - Get denial details
• Get Reasons - Get denial reasons
• By Claim - Get by claim
• Track Appeal - Track appeal
• Get Appeal Status - Get appeal status
• Get Trends - Get denial trends

Practice Resource

• Get Info - Get practice info
• Update Info - Update practice
• Get Settings - Get settings
• Get Locations - Get locations

User Resource

• Get - Get user
• List - List users
• Get Permissions - Get permissions

SFTP Resource

• Upload - Upload file
• Download - Download file
• List Files - List files
• Get Status - Get file status
• Delete - Delete file

Utility Resource

• Validate NPI - Validate NPI number
• Validate Tax ID - Validate tax ID
• Get ICD-10 - Lookup ICD-10 code
• Get CPT - Lookup CPT code
• Get HCPCS - Lookup HCPCS code
• Get POS - Lookup place of service
• Get Modifiers - Lookup modifiers
• Test Connection - Test API connection
• Get API Status - Get API status

Trigger Node

The Office Ally Trigger node supports real-time event monitoring:

Eligibility Triggers

• Eligibility Response Received
• Eligibility Error
• Coverage Changed

Claim Triggers

• Claim Created
• Claim Submitted
• Claim Accepted
• Claim Rejected
• Claim Paid
• Claim Denied
• Claim Status Changed

ERA Triggers

• ERA Received
• Payment Posted
• Adjustment Applied
• Zero Pay Received

Appointment Triggers

• Appointment Created
• Appointment Updated
• Appointment Cancelled
• Patient Checked In
• Patient Checked Out

Patient Triggers

• Patient Created
• Patient Updated
• Insurance Changed

Payment Triggers

• Payment Received
• Payment Posted
• Payment Applied

Batch Triggers

• Batch Submitted
• Batch Completed
• Batch Error

Report Triggers

• Report Ready

Denial Triggers

• Denial Received
• Appeal Due

Usage Examples

Check Patient Eligibility

// Eligibility verification workflow
{
  "resource": "eligibility",
  "operation": "checkEligibility",
  "subscriberId": "ABC123456789",
  "subscriberLastName": "DOE",
  "subscriberFirstName": "JOHN",
  "subscriberDOB": "1980-01-15",
  "payerId": "BCBSIL",
  "serviceType": "30",
  "serviceDate": "2024-03-15"
}

Submit Professional Claim

// Submit 837P claim
{
  "resource": "claim",
  "operation": "submitProfessional",
  "patient": {
    "lastName": "DOE",
    "firstName": "JOHN",
    "dateOfBirth": "1980-01-15",
    "gender": "M",
    "address1": "123 MAIN ST",
    "city": "CHICAGO",
    "state": "IL",
    "zip": "60601"
  },
  "subscriber": {
    "memberId": "ABC123456789",
    "groupNumber": "GRP001",
    "payerId": "BCBSIL"
  },
  "provider": {
    "npi": "1234567890",
    "taxId": "123456789"
  },
  "diagnosis": ["J06.9"],
  "serviceLines": [{
    "procedureCode": "99213",
    "modifiers": ["25"],
    "chargeAmount": 150.00,
    "units": 1,
    "placeOfService": "11",
    "serviceDate": "2024-03-15"
  }]
}

Process ERA/835

// Retrieve and process ERA
{
  "resource": "remittance",
  "operation": "getERA",
  "eraId": "ERA202403150001"
}

// Parse 835 response to get payment details
{
  "resource": "remittance",
  "operation": "parse835",
  "ediContent": "ISA*00*..."
}

Patient Management

// Create patient
{
  "resource": "patient",
  "operation": "create",
  "lastName": "DOE",
  "firstName": "JANE",
  "dateOfBirth": "1985-06-20",
  "gender": "F",
  "ssn": "123-45-6789",
  "phone": "312-555-1234",
  "email": "[email protected]"
}

// Search patients
{
  "resource": "patient",
  "operation": "search",
  "lastName": "DOE",
  "dateOfBirth": "1985-06-20"
}

Appointment Scheduling

// Create appointment
{
  "resource": "appointment",
  "operation": "create",
  "patientId": "PAT001",
  "providerId": "PROV001",
  "appointmentDate": "2024-03-20",
  "appointmentTime": "09:00",
  "duration": 30,
  "appointmentType": "OFFICE_VISIT",
  "reason": "Annual checkup"
}

// Check in patient
{
  "resource": "appointment",
  "operation": "checkIn",
  "appointmentId": "APT001"
}

Payment Posting

// Post insurance payment
{
  "resource": "payment",
  "operation": "post",
  "paymentType": "INSURANCE",
  "payerId": "BCBSIL",
  "checkNumber": "123456",
  "paymentDate": "2024-03-15",
  "amount": 120.00
}

// Apply payment to claim
{
  "resource": "payment",
  "operation": "apply",
  "paymentId": "PMT001",
  "claimId": "CLM001",
  "amount": 120.00
}

Statement Generation

// Generate patient statement
{
  "resource": "statement",
  "operation": "generate",
  "patientId": "PAT001",
  "statementDate": "2024-03-15",
  "includeInsurancePending": true,
  "minimumBalance": 10.00
}

// Batch generate statements
{
  "resource": "statement",
  "operation": "batchGenerate",
  "statementDate": "2024-03-15",
  "agingBucket": "30+"
}

Denial Management

// Get denials by date range
{
  "resource": "denialManagement",
  "operation": "getDenials",
  "startDate": "2024-01-01",
  "endDate": "2024-03-31"
}

// Track appeal
{
  "resource": "denialManagement",
  "operation": "trackAppeal",
  "claimId": "CLM001",
  "appealDate": "2024-03-15",
  "appealReason": "Medical necessity documentation provided",
  "supportingDocs": ["DOC001", "DOC002"]
}

Reporting

// Generate A/R aging report
{
  "resource": "report",
  "operation": "getAging",
  "asOfDate": "2024-03-15",
  "groupBy": "PAYER"
}

// Get denial trends
{
  "resource": "denialManagement",
  "operation": "getTrends",
  "startDate": "2024-01-01",
  "endDate": "2024-03-31",
  "groupBy": "REASON_CODE"
}

Healthcare Concepts

EDI X12 Transactions

| Transaction | Description | |-------------|-------------| | 270 | Eligibility, Coverage, or Benefit Inquiry | | 271 | Eligibility, Coverage, or Benefit Response | | 276 | Healthcare Claim Status Request | | 277 | Healthcare Claim Status Response | | 835 | Healthcare Claim Payment/Advice (ERA) | | 837P | Healthcare Claim Professional | | 837I | Healthcare Claim Institutional | | 997 | Functional Acknowledgment | | 999 | Implementation Acknowledgment |

Clearinghouse Operations

Office Ally acts as a clearinghouse, routing claims between providers and payers. Key functions:

• Claim Scrubbing - Validates claims before submission
• EDI Translation - Converts data to/from X12 format
• Payer Routing - Routes claims to appropriate payers
• Status Tracking - Tracks claim lifecycle
• ERA Distribution - Delivers payment information

Claim Frequency Codes

| Code | Description | |------|-------------| | 1 | Original claim | | 7 | Replacement of prior claim | | 8 | Void/Cancel prior claim |

Adjustment Group Codes

| Code | Description | |------|-------------| | CO | Contractual Obligation | | PR | Patient Responsibility | | PI | Payer Initiated | | OA | Other Adjustment | | CR | Correction and Reversal |

Common CARC Codes

| Code | Description | |------|-------------| | 1 | Deductible Amount | | 2 | Coinsurance Amount | | 3 | Co-payment Amount | | 4 | Procedure code inconsistent with modifier | | 16 | Claim/service lacks information | | 18 | Duplicate claim/service | | 45 | Charge exceeds fee schedule | | 96 | Non-covered charge(s) | | 97 | Benefit for this service is included in another service |

Error Handling

The node provides detailed error messages for common issues:

// Example error responses
{
  "error": "INVALID_NPI",
  "message": "Provider NPI failed Luhn validation",
  "details": { "npi": "1234567890" }
}

{
  "error": "PAYER_NOT_FOUND",
  "message": "Payer ID not found in clearinghouse",
  "details": { "payerId": "UNKNOWN123" }
}

{
  "error": "CLAIM_VALIDATION_FAILED",
  "message": "Claim validation errors",
  "details": {
    "errors": [
      "Missing patient date of birth",
      "Invalid diagnosis code format"
    ]
  }
}

Security Best Practices

1. Credential Security - Store credentials securely; never log passwords
2. PHI Handling - Follow HIPAA guidelines for protected health information
3. Audit Logging - Enable audit trails for all transactions
4. TLS/SSL - All API communications use encrypted connections
5. Access Control - Use role-based access for n8n workflows
6. Data Minimization - Only request/store necessary PHI
7. BAA Compliance - Ensure proper Business Associate Agreements

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA
• Licensing: [email protected]

Licensing

This n8n community node is licensed under the Business Source License 1.1.

Free Use

Permitted for personal, educational, research, and internal business use.

Commercial Use

Use of this node within any SaaS, PaaS, hosted platform, managed service, or paid automation offering requires a commercial license.

For licensing inquiries: [email protected]

See LICENSE, COMMERCIAL_LICENSE.md, and LICENSING_FAQ.md for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• All tests pass
• Code follows existing style
• New features include tests
• Documentation is updated

Support

• Documentation: velobpa.com/docs
• Issues: GitHub Issues
• Email: [email protected]

Acknowledgments

• n8n - Workflow automation platform
• Office Ally - Healthcare clearinghouse services
• Healthcare EDI X12 standards community