Testing with Postman

The BillReview API accepts plain JSON request bodies — no special compression setup is needed in Postman. Send your payload as raw JSON with standard headers.

A future version of the API will require gzip-compressed request bodies. If you are building a production integration, implement gzip compression now so you won’t need to retrofit it later. See Authentication for details.

Step 1 — Get a Bearer token

Create a new POST request in Postman to your Token URL.

Setting	Value
Method	`POST`
URL	Your Token URL (provided at onboarding)
Authorization tab	Basic Auth — enter your Client ID as username, Client Secret as password
Body tab	`x-www-form-urlencoded` with the key/value pairs below

Body parameters:

Key	Value	Required
`grant_type`	`client_credentials`
`scope`	Customer-specific scope, e.g. `billreview:<CustomerScope>`	Only if your onboarding instructions provide one

Send the request. You should receive:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Copy the access_token value — you will use it in Step 2.

Tokens are valid for ~1 hour. You need to re-fetch a new token after it expires.

Step 2 — Call `/v1/review`

1. Create a new POST request:

Setting	Value
Method	`POST`
URL	`{your_api_endpoint}/v1/review`

2. Add headers:

Header	Value
`Authorization`	`Bearer {paste your access_token here}`
`x-api-key`	Your API key
`Content-Type`	`application/json`

3. Set the Body tab to raw → JSON, and paste your bill payload (see Sample Payloads below). That’s it — send the request. Postman automatically sends Accept-Encoding: gzip for responses, so the response body will be decompressed and displayed normally.

Sample Payloads

Institutional bill — CA Inpatient (DRG)

Use this to test a California inpatient hospital bill with a DRG code. This is a complete, working payload.

{
  "Bill": {
    "UniqueID": "3",
    "ProviderType": 2,
    "ZipCode": "93291",
    "MedicareNumber": "050057",
    "DRG": "473",
    "ClaimsOfficeReceivedDate": "2025-07-15T00:00:00",
    "AdmitDate": "2025-07-15T00:00:00",
    "DischargeDate": "2025-07-15T00:00:00",
    "BucketList": []
  },
  "BillOptions": {
    "IsLateFee": true,
    "IsIgnoreTimelyFiling": true
  },
  "Services": [
    {
      "Line": 1,
      "CPT1": "120",
      "CPT2": "",
      "ServiceDate": "2025-07-15T00:00:00",
      "QuantityBilled": 1.0,
      "POS": "21",
      "Charge": 2316.25,
      "BucketList": []
    }
  ],
  "Claim": {
    "DisplayID": "123-123",
    "State": "CA",
    "ZipCode": "92882",
    "StateWhereInjuryOccurred": "CA"
  },
  "Provider": {
    "TaxID": "123456789",
    "PracticeState": "CA",
    "PracticeZipCode": "",
    "BillingZipCode": ""
  },
  "BillHistory": []
}

Professional bill — CA Physician (CMS-1500)

{
  "Bill": {
    "UniqueID": "1001",
    "ProviderType": 1,
    "ZipCode": "90210",
    "BucketList": []
  },
  "BillOptions": {
    "IsLateFee": false,
    "IsIgnoreTimelyFiling": false
  },
  "Services": [
    {
      "Line": 1,
      "CPT1": "99213",
      "CPT2": "",
      "ServiceDate": "2025-07-15T00:00:00",
      "QuantityBilled": 1.0,
      "POS": "11",
      "Charge": 175.00,
      "BucketList": []
    }
  ],
  "Claim": {
    "DisplayID": "CLM-001",
    "State": "CA",
    "ZipCode": "90210",
    "StateWhereInjuryOccurred": "CA"
  },
  "Provider": {
    "TaxID": "123456789",
    "PracticeState": "CA",
    "PracticeZipCode": "90210",
    "BillingZipCode": ""
  },
  "BillHistory": []
}

Expected response

A successful 200 response returns a gzip-compressed JSON body. Postman automatically decompresses this for display. You should see:

{
  "qrCodeID": "3868-4256",
  "qrCodeURL": "https://app.billsentry.net/ID/3868-4256",
  "bill": {
    "totalCharge": 2316.25,
    "totalAllowance": 519.15,
    "totalReduction": 1797.10,
    ...
  },
  "services": [
    {
      "line": 1,
      "allowance": 519.15,
      "reduction": 1797.10,
      "reasonCodesDTO": [ ... ]  // reason code detail objects
    }
  ]
}

The qrCodeURL is a live link to the full RuleTrace™ report for this review.

Common errors in Postman

Error	Likely cause
`401 Missing Bearer token`	`Authorization` header missing or malformed — must be `Bearer {token}` with a space
`401 Invalid token`	Token has expired (1-hour TTL) — re-fetch from the Token URL
`403 Bad API key`	`x-api-key` header value is wrong or missing
`403 Bad API key (malformed)`	The KV entry for this API key contains invalid JSON — contact BillSentry support
`403 Token not valid for this API key`	You are using sandbox M2M credentials with a production API key or vice versa — keep credential sets matched
`400 Invalid request body`	Body is not valid JSON — check for syntax errors
`400 unauthorized_client`	Token request rejected — ensure Body is `x-www-form-urlencoded` with `grant_type=client_credentials` (and a customer-specific `scope` only if your onboarding instructions require one), and that the Client Secret has no extra characters

Getting Started

API Reference

Production Guide

Resources

Step 1 — Get a Bearer token

Step 2 — Call `/v1/review`

Sample Payloads

Institutional bill — CA Inpatient (DRG)

Professional bill — CA Physician (CMS-1500)

Expected response

Common errors in Postman

​Step 1 — Get a Bearer token

​Step 2 — Call /v1/review

​Sample Payloads

​Institutional bill — CA Inpatient (DRG)

​Professional bill — CA Physician (CMS-1500)

​Expected response

​Common errors in Postman

Step 1 — Get a Bearer token

Step 2 — Call `/v1/review`

Sample Payloads

Institutional bill — CA Inpatient (DRG)

Professional bill — CA Physician (CMS-1500)

Expected response

Common errors in Postman