vbd-api

Official JavaScript and TypeScript client for the Veteran Benefit Desk API: structured, source linked VA benefits data with permanent VBD IDs, provenance in every response, and honest review tiers.

You are only charged credits for successful responses. Errors and not found lookups are always free.

Zero dependencies. Works in Node.js 18+ (native fetch), TypeScript types included, ESM and CommonJS.

Install

npm install vbd-api

Quickstart

import { VBD } from "vbd-api";
// or: const { VBD } = require("vbd-api");

const client = new VBD("vbd_sbx_..."); // free key at https://veteranbenefitdesk.com/developers/signup

// Diagnostic codes
const ptsd = await client.getDiagnosticCode("9411");
console.log(ptsd.data.title);            // PTSD
console.log(ptsd.vbd.id);                // VBD:DC:9411
console.log(ptsd.provenance.sources);    // 38 CFR Part 4 ...
console.log(ptsd.citation_text);         // ready to paste attribution line

// Conditions
await client.searchConditions({ q: "knee", limit: 10 });
await client.getCondition("tinnitus");

// VA forms
await client.searchForms({ q: "disability" });
await client.getForm("21-526EZ");

// State benefits (2 credits)
await client.getStateBenefits("TX", { category: "property_tax" });

// Fuzzy resolution: misspellings ok (2 credits)
await client.resolve("tinitus");

// Source check: verify a general statement against the corpus (paid plans, 10 credits per billed call)
const check = await client.sourceCheck("PTSD is rated under diagnostic code 9411", {
  type: "diagnostic_code", // optional corpus filter
  maxSources: 3,           // optional citation cap (1-10)
});
console.log(check.verdict, check.confidence); // supported 1
console.log(check.sources);                   // citations with source_name, vbd_id, source_url, last_reviewed
// Individualized advice requests ("should I file...") return an unbilled abstain verdict.

// Your usage (free)
await client.usage();

// Metering info from the last call
console.log(client.lastReceiptId, client.creditsRemaining);

Errors

All API errors throw VBDError with .status and .detail:

import { VBD, VBDError } from "vbd-api";

try {
  await client.getDiagnosticCode("99999");
} catch (e) {
  if (e instanceof VBDError) {
    console.log(e.status, e.detail); // 404 Unknown diagnostic code... (not billed)
  }
}

TypeScript

Types ship with the package:

import { VBD, VBDError, type VBDEnvelope } from "vbd-api";

const client = new VBD(process.env.VBD_API_KEY!, { timeoutMs: 15000 });
const res: VBDEnvelope = await client.getForm("21-526EZ");

Notes

• Veteran Benefit Desk is independent and not affiliated with the U.S. Department of Veterans Affairs or any government agency.
• Data is general educational information from public sources. It is not legal, medical, individualized claims, or representative advice.
• License: commercial use with attribution ("Data via Veteran Benefit Desk"). Training rights are not granted by default.