> ## 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.

# Introduction

> Workers' compensation bill review built for speed, accuracy, and transparency.

<Note>
  Typical response time: **under 250 ms**. Covers **50 states** (including OWCP).

  Check [API status](https://billsentry.instatus.com) for live uptime.
</Note>

The BillSentry BillReview API allows technology partners and payers to submit bill data and receive structured pricing decisions that can be incorporated directly into claims or adjudication workflows.

## What you get in every response

* Allowed reimbursement amounts per service line
* Reduction explanations and reason codes
* Step-by-step calculation logic (RuleTrace™)
* Fee schedule citations with source URLs
* A shareable QR-linked review report

## How authentication works

BillSentry uses a **two-header model** on every request:

| Header                                 | Purpose                                    |
| -------------------------------------- | ------------------------------------------ |
| `Authorization: Bearer {access_token}` | Proves your identity (short-lived M2M JWT) |
| `x-api-key: {api_key}`                 | Routes the request to your tenant          |

<Warning>
  **Both requests and responses are gzip-compressed.** Send `Content-Type: application/json` and `Content-Encoding: gzip` with a gzip-compressed JSON body — uncompressed requests will be rejected. Successful responses are also returned with `Content-Encoding: gzip`; ensure your client sends `Accept-Encoding: gzip` or handles decompression explicitly.
</Warning>

## Your credentials

BillSentry will provision these during onboarding. Store them securely and treat them the same as passwords.

| Credential           | Description                                     | Example format                                         |
| -------------------- | ----------------------------------------------- | ------------------------------------------------------ |
| **Client ID**        | OAuth2 M2M client identifier                    | `m2m-client-live-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| **Client Secret**    | OAuth2 M2M client secret. Never expose publicly | `Jj8K...` (64+ chars)                                  |
| **API Key**          | Per-tenant key sent in `x-api-key` header       | 64-character hex string (e.g. `a3f2b1c4d5e6f7a8...`)   |
| **Token URL**        | OAuth2 token endpoint                           | Provided during onboarding                             |
| **API Endpoint URL** | Your dedicated API gateway URL                  | Provided during onboarding                             |

<Info>
  Each API customer receives a **dedicated API endpoint URL** provisioned exclusively for your organization. Do not use another customer's endpoint URL.

  Sandbox credentials include a separate endpoint URL and Token URL.
</Info>

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant S as Your System
    participant A as Auth Service
    participant G as Your API Endpoint
    participant E as BillSentry Engine

    Note over S,A: Step 1 — Obtain access token
    S->>A: POST {token_url} — client_id + client_secret (HTTP Basic)
    A-->>S: access_token (JWT, ~1 hour)

    Note over S,G: Step 2 — Submit bill for review
    S->>G: POST /v1/review — Bearer token, x-api-key, gzip body
    activate G
    G->>E: internal routing
    E-->>G: pricing result
    deactivate G
    G-->>S: review result (gzip JSON)
```

Your dedicated API gateway:

1. Validates the Bearer token signature
2. Confirms the token `sub` claim matches your registered M2M client ID
3. Confirms the `x-api-key` is active and bound to your tenant
4. Proxies the request to the BillSentry processing engine (internal, you do not call this directly)