> ## 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.
# Endpoints
> Available API endpoints, request body schemas, and response structure.
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.
**Primary endpoint.** Submit a bill and receive a full pricing decision with RuleTrace™ calculation detail. Body: gzip JSON.
Validate codes and determine the review jurisdiction before submitting for full review. Same request body as `/v1/review`. Body: gzip JSON.
Return a list of hospitals or outpatient/surgery centers for accurate institutional pricing. Body: plain JSON (not gzip).
Identify duplicate or potential duplicate service lines. Same request body as `/v1/review`. Body: gzip JSON.
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`.
**Key naming convention:** Request body fields use **PascalCase** (e.g. `Bill`, `ProviderTaxID`, `CPT1`). The API is case-insensitive for inbound requests. Response fields are returned in camelCase.
***
## Request Body — `/v1/review`, `/v1/validate`, `/v1/duplicates`
The request is a JSON object. `Bill`, `Services`, `Claim`, and `Provider` are required. `BillOptions` and `BillHistory` are optional.
```json Professional (CMS-1500) theme={null}
{
"Bill": {
"UniqueID": "1001",
"ControlNumber": 1001,
"ProviderTaxID": "123456789",
"TypeOfBill": 0,
"ProviderType": 1,
"ZipCode": "90210",
"JurisdictionState": "CA",
"BillReviewState": "CA",
"BucketList": []
},
"BillOptions": {
"IsLateFee": true,
"IsNCCI": true,
"IsMUE": true,
"IsIgnoreTimelyFiling": false
},
"Services": [
{
"Line": 1,
"CPT1": "99213",
"CPT2": "",
"ServiceDate": "2025-07-15T00:00:00",
"QuantityBilled": 1.0,
"POS": "11",
"ModifierList": "25",
"Charge": 175.00,
"BucketList": [],
"ControlNumber": 1001
}
],
"Claim": {
"DisplayID": "CLM-001",
"State": "CA",
"ZipCode": "90210",
"StateOfJurisdiction": "CA",
"DateOfInjury": "2024-06-01T00:00:00"
},
"Provider": {
"TaxID": "123456789",
"NPI": "1234567890",
"PracticeState": "CA",
"PracticeZipCode": "90210"
},
"BillHistory": []
}
```
```json Institutional (UB-04) theme={null}
{
"Bill": {
"UniqueID": "3",
"ControlNumber": 2080,
"ProviderTaxID": "123456789",
"TypeOfBill": 0,
"ProviderType": 2,
"ZipCode": "93291",
"JurisdictionState": "CA",
"BillReviewState": "CA",
"MedicareNumber": "050057",
"DRG": "473",
"AdmitDate": "2025-07-15T00:00:00",
"DischargeDate": "2025-07-15T00:00:00",
"BucketList": []
},
"BillOptions": {
"IsLateFee": true,
"IsMedicareTreatment": true,
"IsIgnoreTimelyFiling": true
},
"Services": [
{
"Line": 1,
"CPT1": "120",
"ServiceDate": "2025-07-15T00:00:00",
"QuantityBilled": 1.0,
"POS": "21",
"Charge": 2316.25,
"BucketList": [],
"ControlNumber": 2080
}
],
"Claim": {
"DisplayID": "123-123",
"State": "CA",
"ZipCode": "92882",
"StateOfJurisdiction": ""
},
"Provider": {
"TaxID": "123456789",
"PracticeState": "CA",
"PracticeZipCode": "93291",
"BillingZipCode": ""
},
"BillHistory": []
}
```
***
## `Bill` object
| Field | Type | Required | Notes |
| --------------------------------- | ------------ | -------- | ---------------------------------------------- |
| `UniqueID` | string (100) | ✓ | Your internal bill identifier |
| `ControlNumber` | int | | Numeric control number |
| `Sequence` | int | | Sequence number for split bills |
| `ProviderTaxID` | string (50) | ✓ | Provider federal tax ID |
| `TypeOfBill` | int (enum) | ✓ | See `TypeOfBill` values |
| `ProviderType` | int (enum) | ✓ | See `ProviderType` values |
| `ZipCode` | string (5) | ✓ | Provider ZIP code |
| `ZipPlusFour` | string (10) | | ZIP+4 |
| `BillReviewState` | string (2) | | 2-letter state — overrides jurisdiction if set |
| `JurisdictionState` | string (2) | | 2-letter jurisdiction state |
| `NPI` | string (10) | | Billing NPI |
| `ProviderSpecialty` | int (enum) | | See `EProviderSpecialty` |
| `MedicareNumber` | string (6) | | CMS certification number (institutional) |
| `OPCERT` | string (7) | | Outpatient certification number |
| `DRG` | string (3) | | DRG code (institutional inpatient) |
| `DRGLevelOfSeverity` | int | | DRG severity level |
| `AdmitDate` | datetime | | Admission date (institutional) |
| `DischargeDate` | datetime | | Discharge date (institutional) |
| `DischargeStatus` | string (2) | | UB-04 discharge status |
| `ClaimsOfficeReceivedDate` | datetime | | Date claims office received the bill |
| `ProcessedDate` | datetime | | Date bill was processed |
| `BillReviewReceivedDate` | datetime | | Date bill review was received |
| `ModifyDate` | datetime | | Last modified date |
| `FacilityName` | string (250) | | Facility name |
| `UB92TypeOfBill` | string (3) | | UB-04 type of bill code |
| `TypeOfAdmission` | int (enum) | | UB-04 type of admission |
| `RateCode` | string (4) | | Rate code |
| `ALCDays` | int | | Alternate level of care days |
| `DeviceCredit` | decimal | | Device credit amount |
| `BillFormType` | int (enum) | | Form type override |
| `BillSource` | int (enum) | | Source of the bill |
| `ICDDiagnosticCodes` | string (150) | | Comma-separated ICD diagnostic codes |
| `ICDProcedureCodes` | string (150) | | Comma-separated ICD procedure codes |
| `ScheduledSurgery` | int (enum) | | Scheduled surgery flag |
| `NoticeNonPaymentDate` | datetime | | Notice of non-payment date |
| `RenderingProviderNPI` | string (10) | | Rendering provider NPI |
| `RenderingProviderRating` | string (10) | | Rendering provider rating |
| `RenderingProviderTaxonomyCode` | string (20) | | Rendering provider taxonomy |
| `RenderingPhysicianNPI` | string (10) | | Rendering physician NPI |
| `RenderingPhysicianLicenseNumber` | string (20) | | Rendering physician license |
| `RenderingPhysicianTaxonomyCode` | string (20) | | Rendering physician taxonomy |
| `BillingProviderNPI` | string (10) | | Billing provider NPI |
| `BillingProviderRating` | string (10) | | Billing provider rating |
| `AttendingProviderRating` | string (10) | | Attending provider rating |
| `AttendingPhysicianLicenseNumber` | string (20) | | Attending physician license |
| `OperatingPhysicianLicenseNumber` | string (20) | | Operating physician license |
| `OtherPhysicianLicenseNumber` | string (20) | | Other physician license |
| `SupervisingProviderRating` | string (10) | | Supervising provider rating |
| `BucketList` | array | | Pass `[]` for standard review |
***
## `BillOptions` object
All fields are optional and override your tenant's default configuration.
| Field | Type | Default | Notes |
| -------------------------------- | ---- | ------- | --------------------------------------- |
| `IsLateFee` | bool | `true` | Apply late fee rules |
| `IsNCCI` | bool | `true` | Apply NCCI edits |
| `IsMUE` | bool | `true` | Apply MUE limits |
| `IsDisallowBeforeDOI` | bool | `true` | Disallow services before date of injury |
| `IsDisallowAfterClosedClaim` | bool | `true` | Disallow services after claim closure |
| `IsPayAboveCharge` | bool | `true` | Cap allowance at billed charge |
| `IsIgnoreTimelyFiling` | bool | `false` | Bypass timely filing limits |
| `IsBoardCertified` | bool | `false` | Provider is board certified |
| `IsSeparateImplantReimbursement` | bool | `false` | Separately reimburse implants |
| `IsSelfInsured` | bool | `false` | Self-insured payer |
| `IsIgnoreClosedFormulary` | bool | `false` | Ignore closed formulary rules |
| `IsIgnoreLimitVisitRule` | bool | `false` | Ignore visit limit rules |
| `UseEAPGBaseRate` | bool | `false` | Use EAPG base rate for outpatient |
| `IsIgnoreHistory` | bool | `false` | Ignore bill history for duplicate check |
| `IsSurchargePaidDirectlyToPool` | bool | `false` | Surcharge paid directly to pool |
| `IsPriorAuthorization` | bool | `false` | Prior authorization obtained |
| `IsDocumentation` | bool | `false` | Required documentation provided |
***
## `Services` array — per service line
| Field | Type | Required | Notes |
| --------------------- | ----------- | -------- | ------------------------------------------------------------------------------------ |
| `Line` | int | ✓ | Line number (1-based) |
| `CPT1` | string (20) | ✓ | CPT, HCPCS, or revenue code |
| `CPT2` | string (20) | | Secondary / compound code |
| `ServiceDate` | datetime | ✓ | Date of service |
| `QuantityBilled` | decimal | ✓ | Units billed |
| `QuantityOverride` | decimal | | Override calculated quantity — omit if not overriding |
| `Charge` | decimal | ✓ | Billed charge for this line |
| `POS` | string (2) | | Place of service code |
| `TOS` | string (2) | | Type of service code |
| `ModifierList` | string (20) | | Comma-separated modifiers (e.g. `"25,59"`) |
| `PPOAllowance` | decimal | | PPO contracted rate — caps allowance if provided; omit or `null` to skip PPO capping |
| `Allowance` | decimal | | Prior allowance (for history/re-review) |
| `TaxCharge` | decimal | | Tax amount billed |
| `TaxAllowance` | decimal | | Tax allowance |
| `TaxRate` | decimal | | Tax rate |
| `Duplicate` | int (enum) | | Duplicate flag |
| `PriorAuthorization` | int (enum) | | Prior auth status for this line |
| `Documentation` | int (enum) | | Documentation status for this line |
| `InvoiceCost` | decimal | | Invoice cost (implants/devices) |
| `ShippingAndHandling` | decimal | | Shipping and handling charge |
| `NPI` | string (10) | | Service-level NPI |
| `ChargemasterCode` | string (50) | | Chargemaster code for outpatient |
| `IsCompoundSterile` | bool | | Compound sterile flag (pharmacy) |
| `CompoundingTime` | int | | Compounding time in minutes |
| `CompoundingFee` | decimal | | Compounding fee |
| `CompoundUniqueID` | string (20) | | Compound drug unique identifier |
| `SterilizationFee` | decimal | | Sterilization fee |
| `ContainerCount` | int | | Number of containers (pharmacy) |
| `DaysSupply` | int | | Days supply (pharmacy) |
| `DispensedAsWritten` | int (enum) | | DAW code (pharmacy) |
| `PrescriberLicense` | string (20) | | Prescriber license number |
| `IsRefill` | bool | | Refill prescription |
| `IsOTCDispensingFee` | bool | | OTC dispensing fee applies |
| `ControlNumber` | int | | Bill control number (required for history bills) |
| `Sequence` | int | | Sequence (history bills) |
| `BucketList` | array | | Pass `[]` for standard review |
***
## `Claim` object
| Field | Type | Notes |
| --------------------- | ----------- | --------------------------- |
| `DisplayID` | string (50) | Your claim identifier |
| `State` | string (2) | Claimant state |
| `ZipCode` | string (5) | Claimant ZIP code |
| `StateOfJurisdiction` | string | Jurisdiction state override |
| `DateOfInjury` | datetime | Date of injury |
| `ClosedDate` | datetime | Claim closure date |
| `Age` | int | Claimant age |
***
## `Provider` object
| Field | Type | Required | Notes |
| ------------------ | ------------ | -------- | ----------------------- |
| `TaxID` | string (50) | ✓ | Provider federal tax ID |
| `NPI` | string (10) | | Provider NPI |
| `License` | string (15) | | Provider license number |
| `Rating` | string (20) | | Provider rating |
| `PracticeName` | string (500) | | Practice name |
| `PracticeAddress1` | string (200) | | Practice address line 1 |
| `PracticeAddress2` | string (200) | | Practice address line 2 |
| `PracticeCity` | string (200) | | Practice city |
| `PracticeState` | string (2) | | Practice state |
| `PracticeZipCode` | string (5) | | Practice ZIP |
| `BillingName` | string (500) | | Billing name |
| `BillingAddress1` | string (200) | | Billing address line 1 |
| `BillingAddress2` | string (200) | | Billing address line 2 |
| `BillingCity` | string (200) | | Billing city |
| `BillingState` | string (2) | | Billing state |
| `BillingZipCode` | string (5) | | Billing ZIP |
***
## `BillHistory` array
Pass prior bills from the same claim to enable duplicate detection and visit-limit enforcement. Each entry has the same structure as the top-level request (a `Bill` object + `Services` array).
```json theme={null}
"BillHistory": [
{
"Bill": { "ControlNumber": 999, "ProviderType": 1, ... },
"Services": [ { "Line": 1, "CPT1": "99213", ... } ]
}
]
```
***
## `TypeOfBill` values
| Value | Name |
| ----- | ------------ |
| `0` | Workers Comp |
| `1` | UCR |
| `2` | OWCP |
| `4` | Auto |
***
## `ProviderType` values
| Value | Name | Value | Name |
| ----- | -------------------------------------- | ----- | ---------------------------------------------- |
| `0` | Unknown | `29` | Nurse Practitioner |
| `1` | Physician | `30` | Nursing Facility |
| `2` | Inpatient | `31` | Occupational Therapist |
| `3` | Outpatient | `32` | Occupational Therapist Assistant |
| `4` | Surgery Center | `33` | Optometrist |
| `5` | Acupuncturist | `34` | Osteopath |
| `6` | Advanced Practice Registered Nurse | `35` | Other |
| `7` | Ambulance Transport Services | `36` | Pain Management |
| `8` | Anesthesiologist | `37` | Pathology Laboratory |
| `9` | Anesthesiologist Assistant | `38` | Pharmacy |
| `10` | Athletic Trainer | `39` | Physical Therapist |
| `11` | Audiologist | `40` | Physical Therapist Assistant |
| `12` | Behavioral Health Counselor | `41` | Physician Assistant |
| `13` | Certified Nurse Assistant | `42` | Podiatrist |
| `14` | Certified Registered Nurse Anesthetist | `43` | Professional Clinical Counselor |
| `15` | Certified Rehabilitation Counselor | `44` | Psychiatric Nurse Practitioner |
| `16` | Chiropractor | `45` | Psychiatrist |
| `17` | Clinical Nurse Specialist | `46` | Psychologist |
| `18` | Clinical Psychologist | `47` | Radiology Facility |
| `19` | Dentist | `48` | Registered Nurse |
| `20` | Dietitian | `49` | Registered Nurse First Assistant |
| `21` | Home Health | `50` | Rehab Nurse |
| `22` | Independent Social Worker | `51` | Respiratory Therapist |
| `23` | Licensed Massage Therapist | `52` | Skilled Nursing Facility |
| `24` | Licensed Surgical Assistant | `53` | Social Worker |
| `25` | Medical Clinic | `54` | Speech Therapist |
| `26` | Medical Supplies | `55` | Urgent Care Center |
| `27` | Mental Health Facility | `56` | Vocation Rehabilitation Case Management Intern |
| `28` | Mental Health Intern | | |
***
## Request Body — `/v1/facility`
This endpoint accepts **plain JSON** — do **not** gzip-compress the body or set `Content-Encoding: gzip`.
```jsonc theme={null}
{
"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.
### Top-level response fields
| Field | Type | Description |
| -------------------- | ------ | -------------------------------------------------------------------- |
| `error` | string | Non-null if the review failed — check this first |
| `qrCodeID` | string | Unique review identifier — use for audit trails and dispute tracking |
| `qrCodeURL` | string | Shareable link to the hosted RuleTrace™ report |
| `logHTML` | string | Self-contained HTML report showing full RuleTrace™ calculation logic |
| `bill` | object | Bill-level results — see `bill` fields below |
| `services` | array | Per-line results — see `services[]` fields below |
| `serviceReasonCodes` | object | Map of `lineNumber → [reason code]` for all lines |
| `logHeader` | object | Metadata about the review run |
| `logDetails` | array | Structured log entries for the review calculation |
***
### `bill` response fields
| Field | Type | Description |
| ------------------------------ | -------- | --------------------------------------------------------------------- |
| `uniqueID` | string | Echoed from request |
| `billReviewState` | string | State that was used for fee schedule lookup |
| `reviewedToState` | string | State actually reviewed under (may differ from submitted) |
| `isPriorAuthorizationRequired` | bool | True if any service line requires prior auth |
| `isDocumentationRequired` | bool | True if any service line requires documentation |
| `totalCharge` | decimal | Sum of all billed charges |
| `totalAllowance` | decimal | Total approved reimbursement (PPO-capped if applicable) |
| `totalUncappedAllowance` | decimal | Allowance before PPO cap |
| `totalReduction` | decimal | Total reduction from billed charges |
| `totalPrePPOAllowance` | decimal | Allowance before PPO adjustment |
| `totalUncappedPrePPOAllowance` | decimal | Pre-PPO allowance before any cap |
| `totalSurcharge` | decimal | Total surcharge amount |
| `totalTaxCharge` | decimal | Total tax charge |
| `totalTaxAllowance` | decimal | Total tax allowance |
| `totalTaxReduction` | decimal | Total tax reduction |
| `fromServiceDate` | datetime | Earliest service date on the bill |
| `toServiceDate` | datetime | Latest service date on the bill |
| `processedDate` | datetime | Date/time the review was processed |
| `facilityName` | string | Resolved facility name |
| `billReviewProcessingTime` | integer | Processing time in milliseconds |
| `isNYC81FormRequired` | bool | NYC C-81 form required |
| `isNYC84FormRequired` | bool | NYC C-84 form required |
| `nmLocationCode` | string | New Mexico location code |
| `reasonCodes` | array | Bill-level reason code IDs |
| `bucketList` | array | Bill-level RuleTrace™ rule trace entries — see Rule Trace Entry below |
| `bucketTotalList` | array | Bill-level bucket totals |
| `billState` | object | State-specific bill metadata |
***
### `services[]` response fields — per line
| Field | Type | Description |
| ------------------------------ | ---------- | --------------------------------------------------------------------- |
| `line` | int | Line number matching the submitted service |
| `cpt1` | string | Resolved CPT / revenue code used for pricing |
| `originalCPT1` | string | CPT1 as submitted (before any code substitution) |
| `description1` | string | Description of CPT1 |
| `descriptionSource1` | int (enum) | Source of the CPT1 description |
| `cpt2` | string | Resolved secondary code |
| `originalCPT2` | string | CPT2 as submitted |
| `description2` | string | Description of CPT2 |
| `quantityBilled` | decimal | Quantity as submitted |
| `quantityUsed` | decimal | Quantity used for pricing (may differ after MUE) |
| `charge` | decimal | Billed charge for this line |
| `allowance` | decimal | Approved reimbursement (PPO-capped if applicable) |
| `uncappedAllowance` | decimal | Allowance before PPO cap |
| `reduction` | decimal | Reduction amount for this line |
| `prePPOAllowance` | decimal | Allowance before PPO adjustment |
| `uncappedPrePPOAllowance` | decimal | Pre-PPO allowance before any cap |
| `taxCharge` | decimal | Tax charge for this line |
| `taxAllowance` | decimal | Tax allowance for this line |
| `taxReduction` | decimal | Tax reduction for this line |
| `taxRate` | decimal | Tax rate applied |
| `invoiceCost` | decimal | Invoice cost (implants/devices) |
| `isPriorAuthorizationRequired` | bool | Prior auth required for this line |
| `isDocumentationRequired` | bool | Documentation required for this line |
| `duplicate` | int (enum) | Duplicate status |
| `cptUsedForPayment` | int (enum) | Which CPT code was used for payment calculation |
| `chargemasterCode` | string | Resolved chargemaster code |
| `chargemasterDescription` | string | Chargemaster code description |
| `reasonCodes` | string | Comma-separated reason code IDs for this line |
| `carcReasonCodes` | string | Comma-separated CARC codes for this line |
| `stateReasonCodes` | string | Comma-separated state-specific reason codes |
| `reasonCodesDTO` | array | Full reason code objects — see Reason Code below |
| `bucketList` | array | Line-level RuleTrace™ rule trace entries — see Rule Trace Entry below |
| `bucketTotalList` | array | Line-level bucket totals |
| `serviceState` | object | State-specific service metadata |
***
### Reason Code fields
| Field | Type | Description |
| ------------------- | ------ | --------------------------------------------------- |
| `id` | int | Reason code ID (1000–4999 system; 5000–9999 custom) |
| `displayID` | string | Display identifier (may differ from `id`) |
| `shortDescription` | string | Human-readable summary |
| `longDescription` | string | Full explanation |
| `bucketHierarchyID` | int | Associated rule bucket |
| `cARC_ID` | string | Corresponding CARC code |
| `cARCDescription` | string | CARC code description |
| `cARCGroupCode` | string | CARC group code |
| `stateReasonCodes` | object | Map of `state → state-specific reason code` |
***
### Rule Trace Entry fields
Each entry in `bucketList` represents one step in the pricing calculation.
| Field | Type | Description |
| ------------------- | ---------- | ------------------------------------------------------- |
| `line` | int | Service line number |
| `bucketHierarchyID` | int | Rule hierarchy identifier |
| `bucketEntryPoint` | int (enum) | How this bucket was triggered |
| `bucketSource` | int (enum) | Source of the pricing value — see `BucketSource` values |
| `bucketSourceID` | string | Source identifier (fee schedule ID, rule ID, etc.) |
| `sourceDescription` | string | Human-readable source description |
| `sourceValue` | decimal | Raw source value |
| `sourcePercent` | decimal | Source percentage applied |
| `sourceAdditional` | decimal | Additional source value |
| `allowance` | decimal | Allowance from this bucket |
| `uncappedAllowance` | decimal | Uncapped allowance from this bucket |
| `percentApplied` | decimal | Percentage applied in this step |
| `reduction` | decimal | Reduction from this bucket |
| `bucketOverride` | int (enum) | Override type applied |
| `fullRuleName` | string | Full name of the pricing rule |
| `triggerCode` | string | Code that triggered this rule |
| `triggerDate` | datetime | Effective date for this rule |
| `percentOfCharge` | decimal | Allowance expressed as percent of charge |
| `requirementURL` | string | Link to the fee schedule or regulation source |
| `reasonCodes` | string | Comma-separated reason codes from this bucket |
| `reasonCodesResult` | array | Full reason code objects for this entry |
***
### Rule Trace — `bucketSource` values
| Value | Name | Description |
| ----- | ------------------ | -------------------------------------- |
| `0` | Unknown | |
| `1` | Charge | Allowance equals the billed charge |
| `2` | Calculated | Fee schedule or rule-based calculation |
| `3` | User | Manual override |
| `4` | PPO | PPO contracted rate |
| `5` | OSR | Other source rate |
| `6` | Utilization Review | UR determination |
| `7` | Adjuster | Adjuster override |
| `8` | Customer Rule | Tenant-specific custom rule |
| `9` | External | External pricing source |
| `10` | Bill Level | Bill-level rule (not line-specific) |
| `11` | Modifier | Modifier-driven adjustment |
***
CPT® © 2025 American Medical Association. All Rights Reserved. Fee schedules, relative value units, conversion factors and/or related components are not assigned by the AMA, are not part of CPT, and the AMA is not recommending their use. The AMA does not directly or indirectly practice medicine or dispense medical services. The AMA assumes no liability for data contained or not contained herein. CPT is a registered trademark of the American Medical Association.