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

# Send claims

> Send one claim, or up to 100 at once as `{ "claims": [ ... ] }`. Needs a key with **Send claims**
(`claims:write`).

- **Idempotent by your claim number.** `claim.claim_number` (the patient control number your billing
  system puts on the claim) is the key. Sending a claim number again returns the claim it became, with
  `created: false`, so retries and re-sends never create duplicates.
- **A reused claim number is refused for that item**, with an `error`: when you already used it 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). Correcting amounts or the payer claim number on a resend is fine.
- **All or nothing on validation.** If any claim in a batch is invalid, nothing is saved and the `422`
  lists every problem by position (`claims[1]: ...`).
- We never echo anything about the patient back.




## OpenAPI

````yaml api-reference/openapi.yaml POST /api/v1/claims
openapi: 3.1.0
info:
  title: Denialbase claims API
  version: '1.0'
  description: >
    Send us the claims your practice wrote off or won't pursue, straight from
    your billing system, and read

    where each one stands. Our team reviews every claim, decides how to appeal
    it and does the work.


    Server to server only: send your API key from your own server, never from a
    browser.
  contact:
    email: support@denialbase.com
servers:
  - url: https://api.denialbase.com
security:
  - apiKey: []
tags:
  - name: Claims
paths:
  /api/v1/claims:
    post:
      tags:
        - Claims
      summary: Send claims
      description: >
        Send one claim, or up to 100 at once as `{ "claims": [ ... ] }`. Needs a
        key with **Send claims**

        (`claims:write`).


        - **Idempotent by your claim number.** `claim.claim_number` (the patient
        control number your billing
          system puts on the claim) is the key. Sending a claim number again returns the claim it became, with
          `created: false`, so retries and re-sends never create duplicates.
        - **A reused claim number is refused for that item**, with an `error`:
        when you already used it 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). Correcting amounts or the payer claim number on a resend is fine.
        - **All or nothing on validation.** If any claim in a batch is invalid,
        nothing is saved and the `422`
          lists every problem by position (`claims[1]: ...`).
        - We never echo anything about the patient back.
      operationId: sendClaims
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ClaimInput'
                - $ref: '#/components/schemas/ClaimBatch'
            examples:
              one:
                summary: One claim
                value:
                  patient:
                    first_name: Jane
                    last_name: Doe
                    date_of_birth: '1980-04-12'
                    account_number: A-1001
                  claim:
                    claim_number: CLM-1001
                    payer_claim_number: '26214000123'
                    payer_name: Blue Shield of California
                    plan_type: commercial
                    date_of_service: '2026-08-01'
                    denial_date: '2026-09-02'
                    procedure_code: '29881'
                    billed_amount: '1250.00'
                    denial_codes:
                      - CO-50
              batch:
                summary: A batch
                value:
                  claims:
                    - patient:
                        first_name: Jane
                        last_name: Doe
                        date_of_birth: '1980-04-12'
                      claim:
                        claim_number: CLM-1001
                        payer_claim_number: E7Q2210045
                        payer_name: Aetna
                        date_of_service: '2026-08-01'
                        billed_amount: '1250.00'
                        denial_codes:
                          - CO-50
                    - patient:
                        first_name: Sam
                        last_name: Lee
                        date_of_birth: '1975-11-03'
                      claim:
                        claim_number: CLM-1002
                        payer_claim_number: '1226488305'
                        payer_name: Cigna
                        date_of_service: '2026-07-14'
                        denied_amount: '380.00'
                        denial_reason: Prior authorization missing
      responses:
        '200':
          description: >-
            Every claim was sent before (or refused per item); nothing new was
            created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendClaimsResponse'
              example:
                claims:
                  - claim_number: CLM-1001
                    id: 952a1c46-5a7e-48e3-9322-5bafeaf02771
                    status: reviewing
                    created: false
                  - claim_number: CLM-1003
                    created: false
                    error: claim.claim_number is already used for a different patient
                  - claim_number: CLM-1004
                    created: false
                    error: claim.claim_number is already used for a different claim
                submission_id: null
        '201':
          description: At least one claim was new.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendClaimsResponse'
              example:
                claims:
                  - claim_number: CLM-1001
                    id: 952a1c46-5a7e-48e3-9322-5bafeaf02771
                    status: received
                    created: true
                submission_id: b24894c4-a3e9-4d6e-a556-a21e86630c4b
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: The request is invalid. Nothing was saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidError'
              example:
                error: Invalid request
                errors:
                  - 'claims[1]: patient.date_of_birth is required (YYYY-MM-DD)'
                  - >-
                    claims[1]: claim.denial_codes or claim.denial_reason is
                    required
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    ClaimInput:
      type: object
      required:
        - patient
        - claim
      properties:
        patient:
          $ref: '#/components/schemas/Patient'
        claim:
          $ref: '#/components/schemas/Claim'
    ClaimBatch:
      type: object
      required:
        - claims
      additionalProperties: false
      properties:
        claims:
          type: array
          minItems: 1
          maxItems: 100
          description: >-
            1 to 100 claims. Each `claim.claim_number` may appear only once per
            batch.
          items:
            $ref: '#/components/schemas/ClaimInput'
    SendClaimsResponse:
      type: object
      required:
        - claims
        - submission_id
      additionalProperties: false
      properties:
        claims:
          type: array
          description: One item per claim you sent, in the same order.
          items:
            $ref: '#/components/schemas/ClaimResult'
        submission_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The submission the new claims joined (it shows in "What you sent").
            `null` when nothing was new.
    InvalidError:
      type: object
      required:
        - error
        - errors
      properties:
        error:
          type: string
        errors:
          type: array
          description: >-
            Every problem, prefixed with the claim's position in a batch.
            Messages name the field and never repeat a value.
          items:
            type: string
    Patient:
      type: object
      required:
        - first_name
        - last_name
        - date_of_birth
      properties:
        first_name:
          type: string
          maxLength: 200
        last_name:
          type: string
          maxLength: 200
        date_of_birth:
          type: string
          format: date
          description: YYYY-MM-DD, not in the future.
        account_number:
          type: string
          maxLength: 200
          description: The patient's account number in your system.
        member_id:
          type: string
          maxLength: 200
          description: The member id on the patient's insurance card.
    Claim:
      type: object
      description: >-
        Needs `billed_amount` or `denied_amount`, and `denial_codes` or
        `denial_reason`.
      required:
        - claim_number
        - payer_claim_number
        - payer_name
        - date_of_service
      properties:
        payer_name:
          type: string
          maxLength: 200
          description: The insurer, as your system names it.
        plan_type:
          type: string
          enum:
            - commercial
            - erisa
            - aca_individual
            - medicare
            - medicare_advantage
            - medi_cal_managed
            - medi_cal_ffs
            - tricare
            - workers_comp
            - other
          description: Leave it out when you don't know it; our team works it out.
        claim_number:
          type: string
          maxLength: 128
          description: >-
            The claim number your billing system put on the claim (the patient
            control number; box 26 of the CMS-1500, CLM01 in an 837, CLP01 in
            the payer's 835). Printable characters. It is your key for the
            claim. A resend with the same number returns the claim it became,
            and you read the claim's status with it. Use a number that is unique
            per claim, and keep it for the life of the claim.
        payer_claim_number:
          type: string
          maxLength: 128
          description: >-
            The number the payer gave the claim when it processed it (the payer
            claim control number, also called ICN or DCN; on the EOB or denial
            letter, CLP07 in the 835). Each payer formats it its own way.
            Printable characters. We need it to appeal; it can change when the
            payer reprocesses the claim, so it isn't the key.
        date_of_service:
          type: string
          format: date
          description: YYYY-MM-DD, not in the future.
        denial_date:
          type: string
          format: date
          description: YYYY-MM-DD, not in the future.
        procedure_code:
          type: string
          maxLength: 200
          description: CPT or HCPCS code, modifiers allowed (`29881-RT`).
        billed_amount:
          type: string
          description: A positive amount, such as `"1250.00"`.
          example: '1250.00'
        denied_amount:
          type: string
          description: A positive amount, such as `"410.00"`.
          example: '410.00'
        denial_codes:
          type: array
          maxItems: 20
          description: >-
            Adjustment and remark codes, such as `CO-50` or `N115`. A
            comma-separated string also works.
          items:
            type: string
        denial_reason:
          type: string
          maxLength: 2000
          description: The denial reason in words, when you have no codes.
        diagnosis_codes:
          type: array
          description: ICD-10 codes.
          items:
            type: string
    ClaimResult:
      type: object
      required:
        - claim_number
        - created
      additionalProperties: false
      properties:
        claim_number:
          type: string
        id:
          type: string
          format: uuid
          description: Our id for the claim. Missing when the item was refused.
        status:
          $ref: '#/components/schemas/ClaimStatus'
        created:
          type: boolean
          description: '`true` when this request created the claim.'
        error:
          type: string
          description: >-
            Why this item was refused (the claim number is already used for a
            different patient, or for a different claim).
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        code:
          type: string
          description: A stable code where one exists, such as `baa_required`.
    RateLimitError:
      type: object
      required:
        - error
        - retry_after
      properties:
        error:
          type: string
        retry_after:
          type: integer
    ClaimStatus:
      type: string
      enum:
        - received
        - reviewing
        - in_report
        - in_appeal
        - recovered
        - closed
      description: |
        - `received`: not reviewed yet
        - `reviewing`: our team is working out how to appeal it
        - `in_report`: it is 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
  responses:
    Unauthorized:
      description: The key is missing, unknown, revoked or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: API key has expired
    Forbidden:
      description: >
        The key lacks the scope this endpoint needs, the organization can't use
        the claims API, or the

        practice has no signed business associate agreement (`code:
        baa_required`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            scope:
              summary: Missing scope
              value:
                error: This API key needs the claims:write scope
            baa:
              summary: No signed business associate agreement
              value:
                error: >-
                  A signed business associate agreement (BAA) with Coastal Ortho
                  is required before any patient data can be received or sent.
                code: baa_required
    TooManyRequests:
      description: >-
        Too many requests. Wait the number of seconds in `Retry-After` (also
        `retry_after`).
      headers:
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: Too many requests. Please try again later.
            retry_after: 42
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >
        Your practice's API key, created in Settings → API keys: `Authorization:
        Bearer <key>`.

````

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