Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.billsentry.net/llms.txt

Use this file to discover all available pages before exploring further.

All endpoints require both auth headers (Authorization and x-api-key). Most accept a gzip-compressed POST body — see per-endpoint notes below for exceptions.

POST /v1/review

Primary endpoint. Submit a bill and receive a full pricing decision with RuleTrace™ calculation detail. Body: gzip JSON.

POST /v1/validate

Validate codes and determine the review jurisdiction before submitting for full review. Same request body as /v1/review. Body: gzip JSON.

POST /v1/facility

Return a list of hospitals or outpatient/surgery centers for accurate institutional pricing. Body: plain JSON (not gzip).

POST /v1/duplicates

Identify duplicate or potential duplicate service lines. Same request body as /v1/review. Body: gzip JSON.

POST /v1/customcodes

Retrieve tenant-specific procedure codes not in the standard CPT/HCPCS list. No request body required.
All paths are appended to your API Endpoint URL — e.g. {your_api_endpoint}/v1/review.

​
Request Body — /v1/review, /v1/validate, /v1/duplicates

The request is a JSON object with four top-level objects. bill, services, claim, and provider are all required. 
{
  "bill": {
    "controlNumber": 1000,           // int, required — your internal bill identifier
    "providerTaxID": "123456789",    // string, required
    "typeOfBill": 0,                 // int enum — see TypeOfBill values below
    "providerType": 1,               // int enum — see ProviderType values below
    "zipCode": "90210",              // string, required — provider ZIP (5 digits)
    "jurisdictionState": "CA",       // string — 2-letter state
    "billReviewState": "CA"          // string — overrides jurisdiction if set
  },
  "claim": {
    "displayID": "CLM-001",          // your claim identifier
    "state": "CA",
    "zipCode": "90210",              // claimant ZIP
    "stateOfJurisdiction": "CA",
    "dateOfInjury": "2024-06-01T00:00:00"
  },
  "provider": {
    "taxID": "123456789",            // string, required
    "npi": "1234567890",
    "practiceState": "CA",
    "practiceZipCode": "90210"
  },
  "services": [
    {
      "line": 1,                     // int, required — line number
      "cpt1": "99213",               // string, required — CPT / HCPCS code
      "cpt2": null,                  // string, optional — secondary code
      "serviceDate": "2025-07-15T00:00:00",
      "quantityBilled": 1.0,         // decimal, required
      "charge": 175.00,              // decimal, required
      "pos": "11",                   // Place of Service (2 chars)
      "modifierList": "25"           // comma-separated modifiers
    }
  ],
  "billOptions": {                   // optional — overrides tenant defaults
    "isLateFee": false,
    "isIgnoreTimelyFiling": false,
    "isMUE": false,
    "isNCCI": false,
    "isPriorAuthorization": false,
    "isDocumentation": false
  }
}

​
typeOfBill values

ValueName
0Workers Comp
1UCR
2OWCP
4Auto

​
providerType values (common)

ValueName
1Physician
2Inpatient
3Outpatient
4Surgery Center
8Anesthesiologist
16Chiropractor
19Dentist
38Pharmacy
39Physical Therapist
52Skilled_Nursing_Facility
Contact BillSentry for the full list of 57 provider type values.

​
Request Body — /v1/facility

This endpoint accepts plain JSON — do not gzip-compress the body or set Content-Encoding: gzip.
{
  "state": "CA",                   // 2-letter state code, required
  "providerType": 2,               // int enum — 2=Inpatient, 3=Outpatient, 4=Surgery_Center
  "effectiveDate": "2025-07-15T00:00:00"
}

​
Request Body — /v1/customcodes

No request body. Send auth headers only (Authorization and x-api-key). The response returns the list of custom codes configured for your tenant.

​
Response Structure — /v1/review

A successful review returns HTTP 200 with a gzip-compressed JSON body (Content-Encoding: gzip). Most HTTP clients decompress this automatically — ensure your client sends Accept-Encoding: gzip or handles decompression explicitly. 
{
  "qrCodeID": "3868-4256",
  "qrCodeURL": "https://app.billsentry.net/ID/3868-4256",
  "logHTML": "<html>...</html>",          // Full RuleTrace™ HTML report

  "bill": {
    "billReviewState": "CA",
    "isPriorAuthorizationRequired": false,
    "isDocumentationRequired": false,
    "totalCharge": 82033.40,
    "totalAllowance": 42150.11,
    "totalUncappedAllowance": 42150.11,   // allowance before PPO cap
    "totalReduction": 39883.29,
    "totalPrePPOAllowance": 42150.11,     // pre-PPO allowance
    "totalSurcharge": 0.00,
    "fromServiceDate": "2025-07-14T00:00:00Z",
    "toServiceDate":   "2025-07-15T00:00:00Z",
    "processedDate":   "2026-04-06T14:44:16Z",
    "bucketTotalList": [ /* bucket-level totals */ ],
    "bucketList":      [ /* rule trace bucket entries */ ]
  },

  "services": [
    {
      "line": 1,
      "cpt1": "99213",
      "charge": 175.00,
      "allowance": 107.90,
      "uncappedAllowance": 107.90,
      "reduction": 67.10,
      "isPriorAuthorizationRequired": false,
      "isDocumentationRequired": false,
      "reasonCodes": "1391,CARC-P12",     // comma-separated reason code IDs
      "carcReasonCodes": "P12",
      "reasonCodesDTO": [                  // full reason code detail (array)
        {
          "id": 1391,
          "displayID": "1391",
          "shortDescription": "Fee schedule allowance",
          "longDescription": "The allowance has been calculated per the applicable fee schedule.",
          "cARC_ID": "P12",
          "cARCDescription": "Workers' compensation jurisdictional fee schedule adjustment."
        }
      ],
      "bucketTotalList": [ /* service-level bucket totals */ ],
      "bucketList":      [ /* service-level rule trace */ ]
    }
  ]
}

​
Key response fields

FieldDescription
qrCodeIDUnique review identifier — use for audit trails and dispute tracking
qrCodeURLShareable link to the hosted RuleTrace™ report
logHTMLSelf-contained HTML report showing full calculation logic
bill.totalAllowanceTotal approved reimbursement for the bill
bill.totalUncappedAllowanceAllowance before any PPO cap is applied
bill.totalReductionTotal reduction from billed charges
bill.isPriorAuthorizationRequiredWhether prior authorization was required for any service
services[].lineLine number matching the submitted service
services[].allowanceApproved reimbursement for this service line
services[].reductionReduction amount for this service line
services[].reasonCodesDTOArray of reason code objects explaining the pricing decision
services[].reasonCodesDTO[].shortDescriptionHuman-readable reason code summary
services[].reasonCodesDTO[].cARC_IDCorresponding CARC code (if applicable)