VerityVerity API
SDKs & Libraries

TypeScript SDK

Official Verity SDK for TypeScript and Node.js with full type definitions

The official Verity TypeScript SDK provides a type-safe way to integrate Medicare coverage intelligence into your TypeScript, JavaScript, and Node.js applications.

Installation

Install via npm, yarn, or pnpm:

npm install verity-api
# or
yarn add verity-api
# or
pnpm add verity-api

Requirements: Node.js 14+ or modern browser with fetch API

Quick Start

import { VerityClient } from 'verity-api';

// Initialize the client
const client = new VerityClient('vrt_live_YOUR_API_KEY');

// Make your first request
const health = await client.health();
console.log(health.data.status);  // "healthy"

Authentication

Set your API key when initializing the client:

import { VerityClient } from 'verity-api';

// Option 1: Pass directly
const client = new VerityClient('vrt_live_YOUR_API_KEY');

// Option 2: With configuration object
const client = new VerityClient({
  apiKey: 'vrt_live_YOUR_API_KEY',
  baseUrl: 'https://verity.backworkai.com/api/v1',  // optional
  timeout: 30000  // optional, in milliseconds
});

// Option 3: From environment variable
const client = new VerityClient(process.env.VERITY_API_KEY!);

Get your API key from the Developer Console.

Common Use Cases

Check if a Procedure Needs Prior Authorization

import { VerityClient } from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

// Check for a knee replacement in Texas
const result = await client.checkPriorAuth({
  procedureCodes: ['27447'],  // Total knee replacement
  diagnosisCodes: ['M17.11'],  // Unilateral primary osteoarthritis, right knee
  state: 'TX'
});

if (result.data.pa_required) {
  console.log('Warning: Prior authorization required!');
  console.log(`Confidence: ${result.data.confidence}`);
  console.log(`Reason: ${result.data.reason}`);
  
  // Show what documentation is needed
  console.log('\nDocumentation checklist:');
  result.data.documentation_checklist?.forEach(item => {
    console.log(`  • ${item}`);
  });
  
  // Show matched policies
  console.log(`\nMatched ${result.data.matched_policies?.length} policies:`);
  result.data.matched_policies?.slice(0, 3).forEach(policy => {
    console.log(`  • ${policy.policy_id}: ${policy.title}`);
  });
} else {
  console.log('No prior authorization needed');
}

Look Up Procedure Code with Coverage Info

import { VerityClient } from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

// Look up a code with RVU data and policies
const result = await client.lookupCode({
  code: '76942',  // Ultrasound guidance
  include: ['rvu', 'policies']
});

const codeData = result.data;
console.log(`Code: ${codeData.code}`);
console.log(`Description: ${codeData.description}`);

// Show reimbursement info
if (codeData.rvu) {
  console.log('\nReimbursement (2026):');
  console.log(`  Work RVU: ${codeData.rvu.work_rvu}`);
  console.log(`  Facility price: $${codeData.rvu.facility_price}`);
  console.log(`  Non-facility price: $${codeData.rvu.non_facility_price}`);
}

// Show coverage policies
if (codeData.policies) {
  console.log(`\nFound ${codeData.policies.length} coverage policies:`);
  codeData.policies.slice(0, 5).forEach(policy => {
    console.log(`  • [${policy.disposition}] ${policy.title}`);
  });
}

Search Coverage Policies by Keyword

import { VerityClient } from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

// Search for policies about diabetes CGM devices
const result = await client.listPolicies({
  q: 'continuous glucose monitoring diabetes',
  policyType: 'LCD',  // Local Coverage Determinations
  status: 'active',
  limit: 10
});

console.log(`Found ${result.data.length} active LCDs about CGM:\n`);

result.data.forEach(policy => {
  console.log(`Policy: ${policy.policy_id}`);
  console.log(`Title: ${policy.title}`);
  console.log(`Jurisdiction: ${policy.jurisdiction || 'National'}`);
  console.log(`Effective: ${policy.effective_date || 'N/A'}`);
  console.log('---');
});

Compare Coverage Across Jurisdictions

import { VerityClient } from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

// Compare ultrasound guidance coverage across different MACs
const result = await client.comparePolicies({
  procedureCodes: ['76942'],
  jurisdictions: ['J05', 'J06', 'J12', 'JM']  // Different MAC jurisdictions
});

const comparison = result.data.comparison;

console.log('Coverage comparison across jurisdictions:\n');
comparison?.forEach(juris => {
  console.log(`${juris.jurisdiction} (${juris.mac_name}):`);
  console.log(`  States: ${juris.states?.join(', ')}`);
  console.log(`  Policies: ${juris.policies?.length}`);
  
  juris.policies?.forEach(policy => {
    console.log(`    • ${policy.policy_id}: ${policy.disposition}`);
  });
  console.log();
});

Monitor Policy Changes

import { VerityClient } from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

// Get policies updated in the last 7 days
const sevenDaysAgo = new Date();
sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);

const result = await client.getPolicyChanges({
  since: sevenDaysAgo.toISOString(),
  changeType: 'updated',
  limit: 20
});

console.log('Policy changes in the last 7 days:\n');

result.data.forEach(change => {
  console.log(`Policy: ${change.policy_id}`);
  console.log(`Change: ${change.change_type}`);
  console.log(`Summary: ${change.change_summary || 'No summary'}`);
  console.log(`Timestamp: ${change.timestamp}`);
  console.log('---');
});

Get Detailed Policy Information

import { VerityClient } from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

// Get full policy details with criteria
const result = await client.getPolicy('L33831', {
  include: ['criteria', 'codes', 'attachments']
});

const policy = result.data;

console.log(`Policy: ${policy.title}`);
console.log(`Type: ${policy.policy_type}`);
console.log(`Status: ${policy.status}`);
console.log(`Effective: ${policy.effective_date || 'N/A'}`);

// Show coverage criteria
if (policy.criteria) {
  console.log('\nCoverage Criteria:');
  Object.entries(policy.criteria).forEach(([section, blocks]) => {
    console.log(`\n${section.toUpperCase()}:`);
    blocks.slice(0, 3).forEach(block => {  // Show first 3
      console.log(`  • ${block.text?.substring(0, 100)}...`);
    });
  });
}

// Show covered codes
if (policy.codes) {
  console.log(`\nCovers ${policy.codes.length} codes`);
  policy.codes.slice(0, 10).forEach(code => {
    console.log(`  • ${code.code} (${code.code_system}): ${code.disposition}`);
  });
}

Search Coverage Criteria

import { VerityClient } from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

// Search for specific coverage criteria about BMI requirements
const result = await client.searchCriteria({
  q: 'BMI greater than 40',
  section: 'indications',
  policyType: 'LCD',
  limit: 10
});

console.log('BMI-related coverage criteria:\n');

result.data.forEach(criteria => {
  console.log(`Policy: ${criteria.policy_id}`);
  console.log(`Section: ${criteria.section}`);
  console.log(`Text: ${criteria.text?.substring(0, 200)}...`);
  console.log(`Tags: ${criteria.tags?.join(', ')}`);
  console.log('---');
});

List MAC Jurisdictions

import { VerityClient } from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

const result = await client.listJurisdictions();

console.log('Medicare Administrative Contractors (MACs):\n');

result.data.forEach(jurisdiction => {
  console.log(`${jurisdiction.jurisdiction_code}: ${jurisdiction.mac_name}`);
  console.log(`  States: ${jurisdiction.states?.join(', ')}`);
  console.log(`  Type: ${jurisdiction.mac_type || 'N/A'}`);
  console.log();
});

Browser Usage

The SDK works in modern browsers using native fetch:

<script type="module">
  import { VerityClient } from 'https://cdn.skypack.dev/verity-api';
  
  const client = new VerityClient('vrt_live_YOUR_API_KEY');
  
  async function checkCode() {
    const result = await client.lookupCode({ code: '76942' });
    console.log(result.data.description);
    document.getElementById('result').textContent = result.data.description;
  }
  
  checkCode();
</script>

<div id="result">Loading...</div>

Error Handling

The SDK provides structured exceptions for different error types:

import {
  VerityClient,
  VerityError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError
} from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

try {
  const result = await client.lookupCode({ code: 'INVALID' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Invalid parameters:', error.message);
    if (error.details) {
      console.error('Details:', error.details);
    }
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limit exceeded. Resets at: ${error.reset}`);
    console.error(`Limit: ${error.limit}, Remaining: ${error.remaining}`);
  } else if (error instanceof VerityError) {
    console.error(`API error: ${error.message} (code: ${error.code})`);
    if (error.hint) {
      console.error(`Hint: ${error.hint}`);
    }
  }
}

Response Format

All methods return typed responses:

interface ApiResponse<T> {
  success: true;
  data: T;
  meta?: {
    request_id?: string;
    timestamp?: string;
    [key: string]: any;
  };
}

// Or error response
interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    hint?: string;
    details?: Record<string, any>;
  };
  meta?: {
    request_id?: string;
    timestamp?: string;
  };
}

TypeScript Integration

The SDK includes complete type definitions:

import { VerityClient, CodeLookupData, PriorAuthResult } from 'verity-api';

const client = new VerityClient(process.env.VERITY_API_KEY!);

// Full type safety with autocomplete
const codeResult = await client.lookupCode({
  code: '76942',
  include: ['rvu', 'policies'],
  jurisdiction: 'JM',
  fuzzy: true
});

// TypeScript knows the exact shape of the response
if (codeResult.success) {
  const data: CodeLookupData = codeResult.data;
  const description: string | null = data.description;
  const found: boolean = data.found;
  const rvu = data.rvu;  // Type: RvuData | undefined
  
  console.log(`${description} - $${rvu?.facility_price}`);
}

Express.js Integration

Example Express.js endpoint using the SDK:

import express from 'express';
import { VerityClient, VerityError } from 'verity-api';

const app = express();
const verity = new VerityClient(process.env.VERITY_API_KEY!);

app.get('/api/check-code/:code', async (req, res) => {
  try {
    const result = await verity.lookupCode({
      code: req.params.code,
      include: ['rvu', 'policies']
    });
    
    res.json(result);
  } catch (error) {
    if (error instanceof VerityError) {
      res.status(error.statusCode || 500).json({
        error: error.message,
        code: error.code
      });
    } else {
      res.status(500).json({ error: 'Internal server error' });
    }
  }
});

app.listen(3000);

Resources

Next Steps

API Reference

Explore all available endpoints

Authentication

Learn about API keys

Rate Limits

Understand usage limits

Error Handling

Handle errors gracefully

On this page

InstallationQuick StartAuthenticationCommon Use CasesCheck if a Procedure Needs Prior AuthorizationLook Up Procedure Code with Coverage InfoSearch Coverage Policies by KeywordCompare Coverage Across JurisdictionsMonitor Policy ChangesGet Detailed Policy InformationSearch Coverage CriteriaList MAC JurisdictionsBrowser UsageError HandlingResponse FormatTypeScript IntegrationExpress.js IntegrationResourcesNext Steps