openapi: 3.0.1
info:
  title: Claim.MD API
  description: >-
    REST API for the Claim.MD medical-claims clearinghouse. The API supports
    electronic claim submission (837P/837I and other formats), claim status and
    response retrieval, electronic remittance advice (835 ERA), real-time
    eligibility (270/271), the payer directory, provider enrollment, appeals,
    and webhook notifications. All requests are authenticated with an AccountKey
    and responses can be returned as XML (default) or JSON via the Accept header.
  termsOfService: https://www.claim.md/terms
  contact:
    name: Claim.MD Support
    url: https://www.claim.md/contact
  version: '1.0'
servers:
  - url: https://svc.claim.md
    description: Claim.MD production API service
security:
  - AccountKey: []
tags:
  - name: Claims
    description: Claim file upload and reconciliation.
  - name: Claim Status
    description: Claim status responses, modifications, and notes.
  - name: ERA
    description: Electronic remittance advice (835) listing and retrieval.
  - name: Eligibility
    description: Real-time eligibility and benefit verification (270/271).
  - name: Reference
    description: Payer directory, enrollment, appeals, and webhooks.
paths:
  /services/upload/:
    post:
      operationId: uploadClaims
      tags:
        - Claims
      summary: Upload a batch claim file
      description: >-
        Upload a file containing 1-2000 claims in 837P, 837I, CSV, JSON, XML,
        XLS, or XLSX format for scrubbing and routing to payers.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - AccountKey
                - File
              properties:
                AccountKey:
                  type: string
                  description: Account authentication key.
                File:
                  type: string
                  format: binary
                  description: Claim batch file.
                Filename:
                  type: string
                  description: Optional original filename.
      responses:
        '200':
          description: Upload accepted with claim and file identifiers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/UploadResponse'
  /services/uploadlist/:
    post:
      operationId: listUploads
      tags:
        - Claims
      summary: List uploaded files
      description: List previously uploaded claim files with counts and dollar amounts.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
              properties:
                AccountKey:
                  type: string
                Page:
                  type: integer
                  description: Page number for pagination.
                UploadDate:
                  type: string
                  description: Filter by upload date (yyyy-mm-dd).
      responses:
        '200':
          description: A list of uploaded files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadListResponse'
  /services/response/:
    post:
      operationId: getClaimResponses
      tags:
        - Claim Status
      summary: Retrieve claim status responses
      description: >-
        Incrementally retrieve claim status responses and acknowledgements.
        Send ResponseID=0 for the initial request, then pass the highest
        returned ResponseID to fetch only newer responses. Max 20,000 results
        per request.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
                - ResponseID
              properties:
                AccountKey:
                  type: string
                ResponseID:
                  type: integer
                  description: Last seen ResponseID; use 0 for the initial request.
                ClaimID:
                  type: string
                  description: Optional filter for a specific claim.
      responses:
        '200':
          description: Claim status responses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseList'
  /services/modify/:
    post:
      operationId: getClaimModifications
      tags:
        - Claim Status
      summary: Retrieve claim modification events
      description: Incrementally retrieve claim field modification history.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
              properties:
                AccountKey:
                  type: string
                ModID:
                  type: integer
                  description: Last seen ModID for incremental updates.
                ClaimMD_ID:
                  type: string
                  description: Optional filter for a specific claim.
                Field:
                  type: string
                  description: Optional field-name filter.
      responses:
        '200':
          description: Claim modification events.
  /services/notes/:
    post:
      operationId: getClaimNotes
      tags:
        - Claim Status
      summary: Retrieve claim notes
      description: Incrementally retrieve user notes attached to claims.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
              properties:
                AccountKey:
                  type: string
                NoteID:
                  type: integer
                  description: Last seen NoteID for incremental updates.
                ClaimMD_ID:
                  type: string
                  description: Optional filter for a specific claim.
      responses:
        '200':
          description: Claim notes.
  /services/archive/:
    post:
      operationId: archiveClaim
      tags:
        - Claim Status
      summary: Archive a claim
      description: Archive or delete one or more claims by claim identifier.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
                - claimid
              properties:
                AccountKey:
                  type: string
                claimid:
                  type: string
                  description: Claim identifier; may be repeated to archive multiple claims.
      responses:
        '200':
          description: Archive status.
  /services/eralist/:
    post:
      operationId: listEra
      tags:
        - ERA
      summary: List electronic remittance advice
      description: >-
        List ERA (835) with payment details, filtered by check, payer, provider,
        or date, with incremental retrieval via ERAID.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
              properties:
                AccountKey:
                  type: string
                CheckDate:
                  type: string
                  description: Check date (mm-dd-yyyy).
                ReceivedDate:
                  type: string
                ReceivedAfterDate:
                  type: string
                CheckNumber:
                  type: string
                CheckAmount:
                  type: string
                PayerID:
                  type: string
                NPI:
                  type: string
                TaxID:
                  type: string
                NewOnly:
                  type: integer
                  description: Return only new ERA (1) or all (0). Defaults to 1.
                ERAID:
                  type: integer
                  description: Last seen ERAID for incremental updates.
                Page:
                  type: integer
      responses:
        '200':
          description: A list of ERA.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EraListResponse'
  /services/era835/:
    post:
      operationId: getEra835
      tags:
        - ERA
      summary: Retrieve raw 835 ERA
      description: Retrieve the raw X12 835 transaction for a single ERA.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
                - eraid
              properties:
                AccountKey:
                  type: string
                eraid:
                  type: integer
      responses:
        '200':
          description: Raw 835 X12 data.
  /services/eradata/:
    post:
      operationId: getEraData
      tags:
        - ERA
      summary: Retrieve structured ERA detail
      description: >-
        Retrieve claim-level remittance detail with adjustment and reason codes
        as structured XML or JSON.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
                - eraid
              properties:
                AccountKey:
                  type: string
                eraid:
                  type: integer
      responses:
        '200':
          description: Structured ERA detail.
  /services/erapdf/:
    post:
      operationId: getEraPdf
      tags:
        - ERA
      summary: Retrieve ERA as PDF
      description: Retrieve a printable remittance report as a Base64-encoded PDF.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
                - eraid
              properties:
                AccountKey:
                  type: string
                eraid:
                  type: integer
                pcn:
                  type: string
                  description: Optional specific patient/account.
      responses:
        '200':
          description: Base64-encoded PDF remittance report.
  /services/elig/:
    post:
      operationId: submitEligibility270
      tags:
        - Eligibility
      summary: Submit eligibility request (270 file)
      description: >-
        Submit a real-time eligibility request as an X12 270 file (one request
        per patient) and receive a 271 response.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - AccountKey
                - File
              properties:
                AccountKey:
                  type: string
                File:
                  type: string
                  format: binary
                  description: X12 270 eligibility request file.
      responses:
        '200':
          description: X12 271 eligibility response.
  /services/eligdata/:
    post:
      operationId: submitEligibilityData
      tags:
        - Eligibility
      summary: Submit eligibility request (field data)
      description: >-
        Submit a real-time eligibility request using structured field data and
        receive detailed benefit coverage in XML or JSON.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EligibilityRequest'
      responses:
        '200':
          description: Eligibility / benefit response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityResponse'
  /services/payerlist/:
    post:
      operationId: listPayers
      tags:
        - Reference
      summary: Retrieve the payer directory
      description: Look up payers and their supported service capabilities.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
              properties:
                AccountKey:
                  type: string
                payerid:
                  type: string
                  description: Optional specific payer ID.
                payer_name:
                  type: string
                  description: Optional payer-name wildcard search.
      responses:
        '200':
          description: Payer directory.
  /services/enroll/:
    post:
      operationId: requestEnrollment
      tags:
        - Reference
      summary: Request provider enrollment
      description: >-
        Initiate a provider enrollment request (ERA, paper, UB, eligibility, or
        attachments) and receive an enrollment link.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
                - payerid
                - enroll_type
                - prov_taxid
              properties:
                AccountKey:
                  type: string
                payerid:
                  type: string
                enroll_type:
                  type: string
                  description: Enrollment type (era, 500, ub, elig, attach).
                prov_taxid:
                  type: string
                prov_npi:
                  type: string
                prov_name_l:
                  type: string
                prov_name_f:
                  type: string
      responses:
        '200':
          description: Enrollment link URL.
  /services/appeal/:
    post:
      operationId: requestAppeal
      tags:
        - Reference
      summary: Request a claim appeal
      description: Initiate a claim appeal and receive an appeal form link.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - AccountKey
              properties:
                AccountKey:
                  type: string
                claimid:
                  type: string
                  description: Claim ID (or use remote_claimid).
                remote_claimid:
                  type: string
                  description: Vendor-side claim identifier.
      responses:
        '200':
          description: Appeal form link URL.
components:
  securitySchemes:
    AccountKey:
      type: apiKey
      in: query
      name: AccountKey
      description: >-
        Account authentication key from Settings > Account Settings in the
        Claim.MD portal. Submitted with each request (as a form field or query
        parameter).
  schemas:
    UploadResponse:
      type: object
      properties:
        fileid:
          type: string
          description: Identifier assigned to the uploaded file.
        claim:
          type: array
          items:
            type: object
            properties:
              claimid:
                type: string
              accept:
                type: string
              field:
                type: string
              error:
                type: string
    UploadListResponse:
      type: object
      properties:
        file:
          type: array
          items:
            type: object
            properties:
              fileid:
                type: string
              filename:
                type: string
              upload_date:
                type: string
              claim_count:
                type: integer
              total_charge:
                type: string
    ResponseList:
      type: object
      properties:
        results:
          type: object
          properties:
            response:
              type: array
              items:
                type: object
                properties:
                  ResponseID:
                    type: integer
                  claimid:
                    type: string
                  remote_claimid:
                    type: string
                  status:
                    type: string
                  fieldname:
                    type: string
                  message:
                    type: string
    EraListResponse:
      type: object
      properties:
        era:
          type: array
          items:
            type: object
            properties:
              eraid:
                type: integer
              payerid:
                type: string
              check_number:
                type: string
              check_amount:
                type: string
              check_date:
                type: string
              npi:
                type: string
    EligibilityRequest:
      type: object
      required:
        - AccountKey
        - ins_name_l
        - ins_name_f
        - payerid
        - pat_rel
        - fdos
        - prov_npi
        - prov_taxid
      properties:
        AccountKey:
          type: string
        ins_name_l:
          type: string
          description: Subscriber last name.
        ins_name_f:
          type: string
          description: Subscriber first name.
        payerid:
          type: string
        pat_rel:
          type: string
          description: Patient relationship (18=Self, G8=Dependent).
        fdos:
          type: string
          description: First date of service (yyyymmdd).
        prov_npi:
          type: string
        prov_taxid:
          type: string
        service_code:
          type: string
          description: Benefit/service type code. Defaults to 30.
        proc_code:
          type: string
          description: CPT procedure code alternative to service_code.
        ins_number:
          type: string
        ins_dob:
          type: string
        ins_sex:
          type: string
        pat_name_l:
          type: string
        pat_name_f:
          type: string
        pat_dob:
          type: string
        pat_sex:
          type: string
        prov_taxid_type:
          type: string
          description: E=EIN, S=SSN.
    EligibilityResponse:
      type: object
      properties:
        elig:
          type: object
          properties:
            ins_name:
              type: string
            payer_name:
              type: string
            plan_status:
              type: string
            benefit:
              type: array
              items:
                type: object
                properties:
                  service_type:
                    type: string
                  coverage_level:
                    type: string
                  benefit_amount:
                    type: string
                  in_network:
                    type: string