NexHealth Claims API

openapi: 3.2.0
info:
  title: NexHealth Adjustment Types Claims API
  description: v3.0.0 and v20240412 are two names for the same API version; the Nex-Api-Version header accepts either value. Welcome to the developer hub and documentation for NexHealth API. This section of guide describes the operations, response parameters, request parameters, and parameter constraints related to User API. The term Operations refer to functions or methods. The operations are included in requests and send to the web server. Each operation performs a different action or a query on database.
  termsOfService: https://www.nexhealth.com/terms-of-service
  contact:
    name: NexHealth
    email: info@nexhealth.com
  license:
    name: NexHealth License 1.0
    url: https://www.nexhealth.com/privacy
  version: v20240412
servers:
- url: https://nexhealth.info
security:
- Authorization: []
tags:
- name: Claims
  description: Claims resources
paths:
  /claims:
    get:
      summary: View claims
      description: This endpoint returns a list of insurance claims for a location. You can filter by patient_id, guarantor_id, provider_id, updated_since or date_of_service, and must provide at least one of these filters. location_id is always required, but does not satisfy the at-least-one-filter requirement on its own. Soft-deleted claims are excluded unless include_deleted is true.
      parameters:
      - in: header
        name: Nex-Api-Version
        description: The NexHealth API version
        required: true
        schema:
          type: string
          default: v3.0.0
      - in: query
        name: subdomain
        description: Used to scope the request to the specified institution
        required: true
        schema:
          type: string
      - in: query
        name: location_id
        description: Used to scope the request to the specified location
        required: true
        schema:
          type: integer
          format: int32
      - in: query
        name: sort
        description: "Optional comma-separated string of fields to sort on.\nInclude a leading dash for descending order.\n\nAvailable fields:\n  * updated_at\n  * -updated_at\n"
        required: false
        schema:
          type: string
      - in: query
        name: patient_id
        description: The ID of the patient associated with the claim
        required: false
        example: 162
        schema:
          type: integer
          format: int32
      - in: query
        name: guarantor_id
        description: The ID of the guarantor associated with the claim
        required: false
        example: 1001
        schema:
          type: integer
          format: int32
      - in: query
        name: provider_id
        description: The ID of the provider associated with the claim
        required: false
        example: 84
        schema:
          type: integer
          format: int32
      - in: query
        name: updated_since
        description: Claims updated at or after the specified time (UTC). The comparison is inclusive, so a record whose updated_at exactly equals the given value is returned
        required: false
        example: '2024-04-12T10:30:00Z'
        schema:
          type: string
          format: date-time
      - in: query
        name: date_of_service
        description: Claims whose date of service exactly matches the specified date
        required: false
        example: '2024-04-12'
        schema:
          type: string
          format: date
      - in: query
        name: include_deleted
        description: Include soft-deleted claims in the results
        required: false
        schema:
          type: boolean
          default: false
      - in: query
        name: start_cursor
        description: First item of the current page. Starts empty
        required: false
        schema:
          type: string
      - in: query
        name: end_cursor
        description: Last item of the current page. Starts empty
        required: false
        schema:
          type: string
      - in: query
        name: per_page
        description: Number of results to return per page. Maximum allowed amount is 1000.
        required: false
        schema:
          type: integer
          format: int32
          default: 5
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V20240412_Entities_Ledger_Insurance_ClaimBasicWithDelete_Collection_Response_WithCursor'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_Forbidden'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_InternalServerError'
      tags:
      - Claims
      operationId: getClaims
  /claims/{id}:
    get:
      summary: View claim
      description: 'This endpoint returns a single insurance claim by its NexHealth id. Use the include parameter to embed related resources: patient, provider, guarantor, charges and/or charge_payouts. Note: when no claim with the given id exists, or it belongs to a location your token cannot access, this endpoint currently responds with HTTP 500 rather than a 404.'
      parameters:
      - in: header
        name: Nex-Api-Version
        description: The NexHealth API version
        required: true
        schema:
          type: string
          default: v3.0.0
      - in: path
        name: id
        required: true
        schema:
          type: integer
          format: int64
      - in: query
        name: subdomain
        description: Used to scope the request to the specified institution
        required: true
        schema:
          type: string
      - in: query
        name: include[]
        description: Resources to be included in the response
        required: false
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - patient
            - provider
            - guarantor
            - charges
            - charge_payouts
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_V20240412_Entities_Ledger_Insurance_Claim_Response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_BadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_NotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/API_Errors_InternalServerError'
      tags:
      - Claims
      operationId: getClaimsId
components:
  schemas:
    API_V20240412_Entities_Ledger_Insurance_Claim_Response:
      type: object
      properties:
        code:
          type: boolean
          example: false
          description: Indicates the success or failure of the request
        description:
          type: string
          example: Description
          description: Additional context on the request to help with debugging.
        error:
          type: array
          items:
            type: string
          example:
          - Error message
          description: Any errors that occur during the execution of the request.
        data:
          $ref: '#/components/schemas/API_V20240412_Entities_Ledger_Insurance_Claim'
        count:
          type: integer
          format: int32
          example: 2
          description: Number of total objects, in case of collection.
      description: API_V20240412_Entities_Ledger_Insurance_Claim_Response model
    API_Errors_BadRequest:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_BadRequest model
    API_V20240412_Entities_Ledger_Insurance_Claim:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
          description: Claim id
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 1
          description: Location id. Null when the claim is not attached to a location
        patient_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 1002
          description: Patient id. Null when the claim is not attached to a patient
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 101
          description: Provider id. Null when the claim is not attached to a provider
        guarantor_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 1001
          description: User id of the patient's responsible party. Null when the claim is not attached to a guarantor
        status:
          type:
          - string
          - 'null'
          enum:
          - draft
          - sent
          - received
          - canceled
          example: sent
          description: Claim status
        received_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2024-06-10T15:16:57.000Z'
          description: Date and time in UTC when the claim was received from insurance
        sent_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2024-06-03T11:23:12.000Z'
          description: Date and time in UTC when the claim was sent to insurance
        note:
          type:
          - string
          - 'null'
          example: Claim was sent to the insurance company
          description: Claim notes
        primary_insurance_plan_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 10021
          description: Id of the primary insurance plan this claim was or will be sent to
        secondary_insurance_plan_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 10022
          description: Id of the secondary insurance plan this claim was or will be sent to
        date_of_service:
          type:
          - string
          - 'null'
          format: date
          example: '2024-06-03'
          description: The date in UTC when the procedures included in the claim occurred
        totals:
          $ref: '#/components/schemas/API_V20240412_Entities_Ledger_ChargeClaimTotals'
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Claim update date in UTC
        deleted_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2022-01-01T00:00:00Z'
          description: The UTC date and time the claim was deleted. Null when the claim is not deleted. Deleted claims are only listed when include_deleted is true
        patient:
          $ref: '#/components/schemas/API_V20240412_Entities_PatientBasic'
        provider:
          $ref: '#/components/schemas/API_V2_Entities_Provider'
        guarantor:
          $ref: '#/components/schemas/API_V2_Entities_User'
        charge_payouts:
          type: array
          items:
            $ref: '#/components/schemas/API_V20240412_Entities_Ledger_ChargePayout'
          description: Billing details for each charge associated with this claim
        charges:
          type: array
          items:
            $ref: '#/components/schemas/API_V20240412_Entities_Ledger_ChargeBasic'
          description: Charges associated with this claim
    API_Errors_Unauthorized:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_Unauthorized model
    API_V2_Entities_Price:
      type: object
      properties:
        amount:
          type: string
          example: '62.00'
          description: The currency value, in whole units (e.g. dollars)
        currency:
          type: string
          example: USD
          description: The ISO currency code
    API_V20240412_Entities_Ledger_ChargeClaimTotals:
      type: object
      properties:
        amount_billed_to_insurance:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        estimated_insurance_payment:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        insurance_payment:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        write_off:
          $ref: '#/components/schemas/API_V2_Entities_Price'
    API_Errors_InternalServerError:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_InternalServerError model
    API_V20240412_Entities_Ledger_Insurance_ClaimBasicWithDelete_Collection_Response_WithCursor:
      type: object
      properties:
        code:
          type: boolean
          example: false
          description: Indicates the success or failure of the request
        description:
          type: string
          example: Description
          description: Additional context on the request to help with debugging.
        error:
          type: array
          items:
            type: string
          example:
          - Error message
          description: Any errors that occur during the execution of the request.
        data:
          type: array
          items:
            $ref: '#/components/schemas/API_V20240412_Entities_Ledger_Insurance_ClaimBasicWithDelete'
        page_info:
          type: object
          example:
            has_previous_page: false
            has_next_page: false
            start_cursor: AAAAA
            end_cursor: BBBBBB
          description: Pagination information that can be used for fetching previous and next pages.
      description: API_V20240412_Entities_Ledger_Insurance_ClaimBasicWithDelete_Collection_Response_WithCursor model
    API_V20240412_Entities_Ledger_ChargePayout:
      type: object
      properties:
        amount_billed_to_insurance:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        estimated_insurance_payment:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        insurance_payment:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        write_off:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        allowed_amount:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        fee_schedule_procedure_code:
          $ref: '#/components/schemas/API_V20240412_Entities_FeeScheduleProcedureCode'
        charge_id:
          type: integer
          format: int64
          example: 1234
          description: The ID of the charge associated with this payout
    API_V20240412_Entities_FeeScheduleProcedureCode:
      type: object
      properties:
        procedure_code_id:
          type:
          - string
          - 'null'
          example: ab123456-11aa-99ff-a111-d1ee12345678
          description: The uuid of the procedure code associated with the fee schedule
        fee:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        code:
          type:
          - string
          - 'null'
          example: D0120
          description: The code of the procedure associated with the fee schedule
        id:
          type: integer
          format: int64
          example: 113
          description: Fee Schedule Procedure Resource id
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 10
          description: The location id of the fee schedule
        fee_schedule_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 1234
          description: The id of the fee schedule associated with the fee schedule procedure
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Fee Schedule Procedure update date in UTC
    API_V20240412_Entities_Ledger_ChargeBasic:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 113
          description: Resource id
        foreign_id:
          type: string
          example: 1234-5678
          description: Unique identifier of this resource from the integrated system
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 10
          description: The ID of the location that this item is for
        patient_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 3
          description: The ID of the patient that this item is for
        guarantor_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 5
          description: The ID of the guarantor that this item is for
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 15
          description: The ID of the provider that this item is for
        procedure_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 34
          description: The ID of the procedure associated with this charge
        procedure_code:
          type:
          - string
          - 'null'
          example: D0120
          description: The procedure code associated with this charge
        updated_at:
          type: string
          format: date-time
          example: '2024-09-05T20:31:17.007Z'
          description: Last updated time for item in UTC
        description:
          type:
          - string
          - 'null'
          example: This is a description
          description: A description of the charge
        fee:
          $ref: '#/components/schemas/API_V2_Entities_Price'
        charged_at:
          type:
          - string
          - 'null'
          format: date
          example: '2024-10-05'
          description: The UTC date charge was made
    API_V2_Entities_User:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 415
          description: User id
        email:
          type:
          - string
          - 'null'
          example: Amy.Ramos@nexhealth.com
          description: User email
        first_name:
          type: string
          example: John
          description: First name
        middle_name:
          type:
          - string
          - 'null'
          example: Anthony
          description: Middle name
        last_name:
          type: string
          example: Smith
          description: Last name
        name:
          type: string
          example: John Smith
          description: Full name
        created_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: User creation date in UTC
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: User last updation date in UTC
        institution_id:
          type: integer
          format: int32
          example: 105
          description: The institution this user belongs to
        foreign_id:
          type:
          - string
          - 'null'
          example: '100437'
          description: Foreign Id is a unique identifier from the integrated system
        foreign_id_type:
          type: string
          example: --DataSource-
          description: Foreign Id type is a unique string identifier for the integrated system
        bio:
          type: object
          example:
            city: New York
            state: NY
            gender: Female
            zip_code: '20814'
            new_patient: false
            non_patient: true
            phone_number: '5163042196'
            date_of_birth: '1964-05-03'
            address_line_1: ''
            address_line_2: ''
            street_address: ''
            cell_phone_number: ''
            home_phone_number: ''
            work_phone_number: ''
          description: Patient biographical data, fields shown in our example response represent all possible data we retrieve but depending on system and what is actually saved in the health records system you cannot assume any field will consistently be returned
        inactive:
          type: boolean
          example: false
          description: Is the user inactivated?
        last_sync_time:
          type:
          - string
          - 'null'
          format: date-time
          example: '2024-04-12T10:30:00Z'
          description: The most recent time the resource's data changed meaningfully at the source
    API_V20240412_Entities_PatientBasic:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 415
          description: User id
        email:
          type:
          - string
          - 'null'
          example: Amy.Ramos@nexhealth.com
          description: User email
        first_name:
          type: string
          example: John
          description: First name
        middle_name:
          type:
          - string
          - 'null'
          example: Anthony
          description: Middle name
        last_name:
          type: string
          example: Smith
          description: Last name
        name:
          type: string
          example: John Smith
          description: Full name
        created_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: User creation date in UTC
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: User last updation date in UTC
        institution_id:
          type: integer
          format: int32
          example: 105
          description: The institution this user belongs to
        foreign_id:
          type:
          - string
          - 'null'
          example: '100437'
          description: Foreign Id is a unique identifier from the integrated system
        foreign_id_type:
          type: string
          example: --DataSource-
          description: Foreign Id type is a unique string identifier for the integrated system
        bio:
          type: object
          example:
            city: New York
            state: NY
            gender: Female
            zip_code: '20814'
            new_patient: false
            non_patient: true
            phone_number: '5163042196'
            date_of_birth: '1964-05-03'
            address_line_1: ''
            address_line_2: ''
            street_address: ''
            cell_phone_number: ''
            home_phone_number: ''
            work_phone_number: ''
          description: Patient biographical data, fields shown in our example response represent all possible data we retrieve but depending on system and what is actually saved in the health records system you cannot assume any field will consistently be returned
        inactive:
          type: boolean
          example: false
          description: Is the user inactivated?
        last_sync_time:
          type:
          - string
          - 'null'
          format: date-time
          example: '2024-04-12T10:30:00Z'
          description: The most recent time the resource's data changed meaningfully at the source
        guarantor_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 472
          description: User id of this patient's responsible party
        billing_type:
          type:
          - string
          - 'null'
          example: Standard Billing - finance charges
          description: Used by practices in some integrated systems to categorize and filter patients when creating reports, requesting payments, and performing other related office tasks. Some integrated systems call this an account type rather than a billing type
        chart_id:
          type:
          - string
          - 'null'
          example: '017407'
          description: User-facing ID for referencing patient data, used in some integrated systems. Depending on the system, the chart ID supplements or replaces the foreign_id as the ID visible to EHR users
        preferred_language:
          type:
          - string
          - 'null'
          example: es
          description: Patient's preferred language as an ISO 639-1 code, if specified in the integrated system
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 23
          description: User id of this patient's primary provider
    API_V20240412_Entities_Ledger_Insurance_ClaimBasicWithDelete:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
          description: Claim id
        location_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 1
          description: Location id. Null when the claim is not attached to a location
        patient_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 1002
          description: Patient id. Null when the claim is not attached to a patient
        provider_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 101
          description: Provider id. Null when the claim is not attached to a provider
        guarantor_id:
          type:
          - integer
          - 'null'
          format: int32
          example: 1001
          description: User id of the patient's responsible party. Null when the claim is not attached to a guarantor
        status:
          type:
          - string
          - 'null'
          enum:
          - draft
          - sent
          - received
          - canceled
          example: sent
          description: Claim status
        received_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2024-06-10T15:16:57.000Z'
          description: Date and time in UTC when the claim was received from insurance
        sent_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2024-06-03T11:23:12.000Z'
          description: Date and time in UTC when the claim was sent to insurance
        note:
          type:
          - string
          - 'null'
          example: Claim was sent to the insurance company
          description: Claim notes
        primary_insurance_plan_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 10021
          description: Id of the primary insurance plan this claim was or will be sent to
        secondary_insurance_plan_id:
          type:
          - integer
          - 'null'
          format: int64
          example: 10022
          description: Id of the secondary insurance plan this claim was or will be sent to
        date_of_service:
          type:
          - string
          - 'null'
          format: date
          example: '2024-06-03'
          description: The date in UTC when the procedures included in the claim occurred
        totals:
          $ref: '#/components/schemas/API_V20240412_Entities_Ledger_ChargeClaimTotals'
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: Claim update date in UTC
        deleted_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2022-01-01T00:00:00Z'
          description: The UTC date and time the claim was deleted. Null when the claim is not deleted. Deleted claims are only listed when include_deleted is true
    API_Errors_Forbidden:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_Forbidden model
    API_Errors_NotFound:
      type: object
      properties:
        code:
          type: boolean
          description: Indicates the success or failure of the request.
        description:
          type: string
          description: Additional context about the request to help with debugging.
        data:
          type: object
        error:
          type: array
          items:
            type: string
          description: Any errors that occured during the execution of the request.
      description: API_Errors_NotFound model
    API_V2_Entities_Provider:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 415
          description: User id
        email:
          type:
          - string
          - 'null'
          example: Amy.Ramos@nexhealth.com
          description: User email
        first_name:
          type: string
          example: John
          description: First name
        middle_name:
          type:
          - string
          - 'null'
          example: Anthony
          description: Middle name
        last_name:
          type: string
          example: Smith
          description: Last name
        name:
          type: string
          example: John Smith
          description: Full name
        created_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: User creation date in UTC
        updated_at:
          type: string
          format: date-time
          example: '2020-06-05T20:16:57.007Z'
          description: User last updation date in UTC
        institution_id

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nexhealth/refs/heads/main/openapi/nexhealth-claims-api-openapi.yml