NexHealth SDK for JavaScript/TypeScript

TypeScript SDK for NexHealth APIs. This library provides type-safe wrappers for NexHealth's REST APIs, enabling integration with dozens of health record systems using a single universal API.

[!NOTE] This is an unofficial third-party SDK for integrating with NexHealth APIs. It is not affiliated with or endorsed by NexHealth. Learn more about us.

Features

• Complete TypeScript definitions for API methods and responses
• Type-safe client for NexHealth REST APIs
• Flexible logging with support for custom loggers (Winston, Pino, etc.)

Table of Contents

• Installation
• Quick Start
• API Reference
  • Authentication
  • Patients
  • Charges
  • Claims
  • Payments
  • Payment Types
• TypeScript Support
• Logging
• Contributing
• License
• Resources
• Support
• About Us

Requirements

• Node.js >= 20.x
• TypeScript >= 5.0 (for development)

Installation

npm install @fincuratech/nexhealth-sdk-js

or with yarn:

yarn add @fincuratech/nexhealth-sdk-js

or with pnpm:

pnpm add @fincuratech/nexhealth-sdk-js

Quick Start

import { createNexHealthClient } from '@fincuratech/nexhealth-sdk-js';

// Initialize the client with your NexHealth API key
const nexhealth = createNexHealthClient('your-nexhealth-api-key');

// Authenticate first (required before making other API calls)
await nexhealth.authenticate();

// Example: List patients for a location
const patients = await nexhealth.patients.list({
  location_id: 123,
  subdomain: 'my-practice',
});

API Reference

Authentication

authenticate()

Authenticate with the NexHealth API. Must be called before making any other API requests. The bearer token is valid for 1 hour.

await nexhealth.authenticate();

Additional methods:

• isAuthenticated() - Check if authenticated
• getToken() - Get current token (or null)
• clearAuth() - Clear authentication

📖 Authentication Documentation

Patients

patients.list(params)

Retrieve patients for a location.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | location_id | number | ✓ | Location ID | | subdomain | string | ✓ | Institution subdomain | | id | number | | Filter by patient ID | | name | string | | Fuzzy search across first and last name | | first_name | string | | Filter by first name | | last_name | string | | Filter by last name | | email | string | | Filter by email | | phone_number | string | | Filter by phone | | date_of_birth | string | | Filter by DOB (YYYY-MM-DD) | | provider_id | number | | Filter by patient foreign_id from EHR | | new_patient | boolean | | Filter new patients | | inactive | boolean | | Filter inactive patients | | since | string | | Updated since timestamp | | page | number | | Page number | | per_page | number | | Results per page |

Returns: Promise<NexHealthPatient[]>

const patients = await nexhealth.patients.list({
  location_id: 123,
  subdomain: 'my-practice',
});

// With filters
const filtered = await nexhealth.patients.list({
  location_id: 123,
  subdomain: 'my-practice',
  first_name: 'John',
  last_name: 'Doe',
});

📖 Patients API Documentation

Charges

[!NOTE] Only supported for Dentrix, Dentrix Enterprise, Eaglesoft, and Open Dental.

charges.list(params)

Retrieve charges for a location.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | location_id | number | ✓ | Location ID | | subdomain | string | ✓ | Institution subdomain | | patient_id | number | | Filter by patient ID | | provider_id | number | | Filter by provider ID | | guarantor_id | number | | Filter by guarantor ID | | procedure | string | | Filter by procedure code | | updated_since | string | | Updated since timestamp | | page | number | | Page number | | per_page | number | | Results per page |

Returns: Promise<NexHealthCharge[]>

const charges = await nexhealth.charges.list({
  location_id: 123,
  subdomain: 'my-practice',
  patient_id: 456,
});

📖 Charges API Documentation

Claims

[!NOTE] Only supported for Dentrix, Dentrix Enterprise, Eaglesoft, and Open Dental.

claims.list(params)

Retrieve insurance claims for a location.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | location_id | number | ✓ | Location ID | | subdomain | string | ✓ | Institution subdomain | | patient_id | number | | Filter by patient ID | | provider_id | number | | Filter by provider ID | | guarantor_id | number | | Filter by guarantor ID | | updated_since | string | | Updated since timestamp | | page | number | | Page number | | per_page | number | | Results per page |

Returns: Promise<NexHealthClaim[]>

const claims = await nexhealth.claims.list({
  location_id: 123,
  subdomain: 'my-practice',
  patient_id: 456,
});

📖 Claims API Documentation

Payments

[!NOTE] Only supported for Dentrix, Dentrix Enterprise, Eaglesoft, and Open Dental.

payments.create(params, body)

Create a payment in the EHR.

Query Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | location_id | number | ✓ | Location ID | | subdomain | string | ✓ | Institution subdomain |

Body Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | patient_id | number | ✓ | Patient ID | | amount | number | ✓ | Amount (negative for received) | | payment_type_id | number | * | Payment type ID | | type_name | string | * | Payment type name | | transaction_id | string | | Unique ID for idempotency | | paid_at | string | | ISO 8601 payment timestamp | | charge_splits | object | | Split across charges | | provider_splits | object | | Split across providers | | notes | string | | Payment notes | | currency | string | | Currency (default: USD) |

* Either payment_type_id or type_name must be provided.

Returns: Promise<NexHealthPayment>

const payment = await nexhealth.payments.create(
  { location_id: 123, subdomain: 'my-practice' },
  {
    patient_id: 456,
    amount: -100,
    payment_type_id: 10,
    transaction_id: 'API:payment-001',
  }
);

// With charge splits
const payment = await nexhealth.payments.create(
  { location_id: 123, subdomain: 'my-practice' },
  {
    patient_id: 456,
    amount: -138,
    payment_type_id: 10,
    charge_splits: { '789': -100, '790': -38 },
  }
);

📖 Payments API Documentation

Payment Types

[!NOTE] Only supported for Dentrix, Dentrix Enterprise, Eaglesoft, and Open Dental.

paymentTypes.list(params)

List payment types for a location.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | location_id | number | ✓ | Location ID | | subdomain | string | ✓ | Institution subdomain |

Returns: Promise<NexHealthPaymentType[]>

const types = await nexhealth.paymentTypes.list({
  location_id: 123,
  subdomain: 'my-practice',
});

const creditCard = types.find((t) => t.name === 'Credit Card');

📖 Payment Types API Documentation

TypeScript Support

This SDK is written in TypeScript and provides full type definitions.

Available Types

import type {
  // Client
  NexHealthClient,
  
  // Patients
  NexHealthPatient,
  NexHealthPatientBio,
  NexHealthPatientsQueryParams,
  
  // Charges
  NexHealthCharge,
  NexHealthChargesQueryParams,
  
  // Claims
  NexHealthClaim,
  NexHealthClaimTotals,
  NexHealthClaimsQueryParams,
  
  // Payments
  NexHealthPayment,
  NexHealthPaymentCreateBody,
  NexHealthPaymentCreateParams,
  NexHealthChargeSplits,
  NexHealthProviderSplits,
  
  // Payment Types
  NexHealthPaymentType,
  NexHealthPaymentTypesQueryParams,
  
  // Common
  NexHealthMoneyAmount,
  NexHealthApiResponse,
} from '@fincuratech/nexhealth-sdk-js';

Logging

The SDK is silent by default. Enable logging for debugging:

import { createNexHealthClient, setLogger, createConsoleLogger } from '@fincuratech/nexhealth-sdk-js';

setLogger(createConsoleLogger('debug'));

const nexhealth = createNexHealthClient('your-api-key');

Available log levels: 'debug' | 'info' | 'warn' | 'error'

Custom Logger

Integrate any logging framework by implementing the Logger interface:

import { setLogger, type Logger } from '@fincuratech/nexhealth-sdk-js';

const customLogger: Logger = {
  debug: (message, meta) => { /* ... */ },
  info: (message, meta) => { /* ... */ },
  warn: (message, meta) => { /* ... */ },
  error: (message, meta) => { /* ... */ },
};

setLogger(customLogger);

Contributing

Contributions are welcome. Please follow these guidelines:

Development Setup

Use pnpm - npm has issues with platform-specific native bindings (especially on macOS).

pnpm install
pnpm test
pnpm run lint
pnpm run build

Guidelines

• Write tests for new features
• Follow the existing code style
• Update documentation for API changes
• Ensure all tests pass before submitting PRs
• Use conventional commit messages

License

This project is licensed under the MIT License - see the LICENSE file for full details.

Copyright (c) 2024 Fincura Technologies, Inc.

Resources

• NexHealth API Documentation
• NexHealth Developer Portal

Support

For issues and questions:

• Open an issue on GitHub
• Contact Us at [email protected]

About Us

Developed by Fincura Technologies, Inc.

We provide healthcare practices and providers with automated insurance payment reconciliation and posting software, enabling provider staff to get paid 2.5x faster by payers and automate 40 hours per month in payment reconciliations.

Our platform leverages multiple sources to access ERA 835 payment remittance details of health insurance claims, including direct payer integrations and clearinghouse partners. This SDK powers integrations with NexHealth's APIs for patient management, scheduling, and practice data synchronization.