> ## Documentation Index
> Fetch the complete documentation index at: https://docs.denialbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claims API

> Send claims from your billing system and read where each one stands.

The claims API lets your practice's billing system or IT team send us the denied claims you wrote off or won't
pursue, without anyone uploading files. Our team reviews every claim, decides how to appeal it and does the work,
exactly as for claims you send in the console. The same API tells you where each claim stands.

There are two endpoints:

| | |
| - | - |
| [`POST /api/v1/claims`](/api-reference/endpoints/send-claims) | Send one claim, or up to 100 at once. |
| [`GET /api/v1/claims/status`](/api-reference/endpoints/read-a-claims-status) | Read one claim's status by its claim number. |

## Base URL

```text theme={null}
https://api.denialbase.com
```

## Before you start

* Your practice's [business associate agreement](/guides/getting-started#the-business-associate-agreement) is
  signed. Until it is, every call answers `403` with `code: baa_required`.
* An owner or admin created an API key in **Settings → API keys** with **Send claims** and **Read claim status**.
  See [Authentication](/api-reference/authentication).
* Calls come from your server. Never put the key in a web page or app.

## Quickstart

<Steps>
  <Step title="Send a claim">
    Send the claim number your billing system put on the claim as `claim.claim_number` (your key for the claim),
    and the payer's claim number from the EOB as `claim.payer_claim_number`.

    ```bash theme={null}
    curl -X POST https://api.denialbase.com/api/v1/claims \
      -H "Authorization: Bearer $DENIALBASE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "patient": { "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1980-04-12",
                     "account_number": "A-1001" },
        "claim": { "claim_number": "YOUR-CLAIM-NUMBER", "payer_claim_number": "PAYER-CLAIM-NUMBER",
                   "payer_name": "Blue Shield", "date_of_service": "2026-08-01", "denial_date": "2026-09-02",
                   "procedure_code": "29881", "billed_amount": "1250.00", "denial_codes": ["CO-50"] }
      }'
    ```

    ```json theme={null}
    {
      "claims": [
        { "claim_number": "YOUR-CLAIM-NUMBER", "id": "952a1c46-5a7e-48e3-9322-5bafeaf02771",
          "status": "received", "created": true }
      ],
      "submission_id": "b24894c4-a3e9-4d6e-a556-a21e86630c4b"
    }
    ```
  </Step>

  <Step title="Read its status">
    ```bash theme={null}
    curl -G https://api.denialbase.com/api/v1/claims/status \
      -H "Authorization: Bearer $DENIALBASE_API_KEY" \
      --data-urlencode "claim_number=YOUR-CLAIM-NUMBER"
    ```

    ```json theme={null}
    {
      "claim": {
        "claim_number": "YOUR-CLAIM-NUMBER",
        "id": "952a1c46-5a7e-48e3-9322-5bafeaf02771",
        "status": "reviewing",
        "signing": { "status": "not_decided", "appeal_button": false }
      }
    }
    ```
  </Step>
</Steps>

## Good to know

* **Which number goes where.** There is no claim number shared across payers. The key is the claim number your
  billing system already puts on the claim (the patient control number: box 26 of the CMS-1500, CLM01 in an 837),
  sent as `claim.claim_number`. The payer's own number for the claim (ICN or DCN, from the EOB or denial letter)
  goes in `claim.payer_claim_number`: we need it to appeal, but it can change when the payer reprocesses the
  claim, so it isn't the key.
* **Send a claim again safely.** We recognize claims by their claim number: sending one again returns the claim it
  became, with `created: false`. Retrying after a timeout, or re-sending everything each night, never creates a
  duplicate. A resend may correct the amounts and the payer claim number.
* **One claim number, one claim.** A claim number you already used for a different patient (name and date of
  birth), or for a different claim of the same patient (another date of service or procedure code), is refused
  for that claim, with an `error`, so a reused number never stands in for a new claim.
* **A batch is all or nothing on validation.** If one claim in a batch is invalid, nothing is saved and the error
  lists every problem. See [Errors](/api-reference/errors).
* **We never echo patient details back.** Responses carry your claim number, our id and the status.
* **You don't choose routes.** Our team decides how each claim is appealed. When a patient's signature is needed,
  `signing` tells you, and gives you the link for the [appeal button](/guides/patients#the-appeal-button) while
  it's switched on.

## Claim statuses

| `status` | Means |
| - | - |
| `received` | Not reviewed yet. |
| `reviewing` | Our team is working out how to appeal it. |
| `in_report` | It's in a report we delivered to you. |
| `in_appeal` | Our team opened its case. |
| `recovered` | The payer paid, in full or in part. |
| `closed` | The appeal ended without payment. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.