> ## 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.
# Testing with Postman
> Step-by-step guide to authenticating and calling the BillSentry API from 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](/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:` | Only if your onboarding instructions provide one |
Send the request. You should receive:
```json theme={null}
{
"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](#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.
```json theme={null}
{
"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)
```json theme={null}
{
"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:
```json theme={null}
{
"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 |