openapi: 3.2.0
info:
  title: Reference Write Offs API
  version: 1.0.0
servers:
- url: https://pre-api.joincandidhealth.com
  description: Production
- url: https://pre-api-staging.joincandidhealth.com
  description: Staging
- url: https://sandbox-pre-api.joincandidhealth.com
  description: CandidSandbox
- url: https://staging-pre-api.joincandidhealth.com
  description: CandidStaging
- url: http://localhost:4000
  description: Local
- url: https://api.joincandidhealth.com
  description: Production
- url: https://api-staging.joincandidhealth.com
  description: Staging
- url: https://sandbox-api.joincandidhealth.com
  description: CandidSandbox
- url: https://staging-api.joincandidhealth.com
  description: CandidStaging
- url: http://localhost:5050
  description: Local
tags:
- name: Write Offs
paths:
  /api/write-offs/v1:
    get:
      operationId: get_multi
      summary: Get all write-offs
      description: Returns all write-offs satisfying the search criteria.
      tags:
      - Write Offs
      parameters:
      - name: limit
        in: query
        description: Defaults to 100. The value must be greater than 0 and less than 1000.
        required: false
        schema:
          type: integer
      - name: patient_external_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_PatientExternalId'
      - name: payer_uuid
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_payers_v3_PayerUuid'
      - name: service_line_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_ServiceLineId'
      - name: claim_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_ClaimId'
      - name: billing_provider_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_ProviderId'
      - name: sort
        in: query
        description: Defaults to write_off_timestamp
        required: false
        schema:
          $ref: '#/components/schemas/type_write-offs_v1_WriteOffSortField'
      - name: sort_direction
        in: query
        description: Sort direction. Defaults to descending order if not provided.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortDirection'
      - name: page_token
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_PageToken'
      - name: account_types
        in: query
        description: Filters the returned values to include only the provided account types.
        required: false
        schema:
          $ref: '#/components/schemas/type_financials_AccountType'
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_write-offs_v1_WriteOffsPage'
    post:
      operationId: create
      summary: Create write-off
      description: 'Creates one or many write-offs applied toward a specific service line,

        claim, or billing provider.'
      tags:
      - Write Offs
      parameters:
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_write-offs_v1_CreateWriteOffsResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                write_offs:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_write-offs_v1_WriteOffCreate'
              required:
              - write_offs
  /api/write-offs/v1/{write_off_id}:
    get:
      operationId: get
      summary: Get write-off
      description: Retrieves a previously created write off by its `write_off_id`.
      tags:
      - Write Offs
      parameters:
      - name: write_off_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_write-offs_v1_WriteOff'
  /api/write-offs/v1/{write_off_id}/revert:
    post:
      operationId: revert
      summary: Revert write-off
      description: Reverts a write off given a `write_off_id`.
      tags:
      - Write Offs
      parameters:
      - name: write_off_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_write-offs_v1_WriteOff'
  /api/write-offs/v1/{adjustment_id}/revert:
    post:
      operationId: revert-insurance-balance-adjustment
      summary: Revert Insurance Balance Adjustment
      description: Reverts an Insurance Balance Adjustment given an `adjustment_id`
      tags:
      - Write Offs
      parameters:
      - name: adjustment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_AdjustmentId'
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_write-offs_v1_WriteOff'
  /api/write-offs/v1/{adjustment_id}/revert-era-originated:
    post:
      operationId: revert-era-originated-insurance-balance-adjustment
      summary: Revert ERA-originated Insurance Balance Adjustment
      description: Reverts an ERA-originated Insurance Balance Adjustment given an `adjustment_id`
      tags:
      - Write Offs
      parameters:
      - name: adjustment_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_AdjustmentId'
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_AdjustmentId'
components:
  schemas:
    type_write-offs_v1_CreateWriteOffsResponse:
      type: object
      properties:
        write_offs:
          type: array
          items:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOff'
      required:
      - write_offs
      title: CreateWriteOffsResponse
    type_non-insurance-payers_v1_NonInsurancePayer:
      type: object
      properties:
        non_insurance_payer_id:
          $ref: '#/components/schemas/type_non-insurance-payers_v1_NonInsurancePayerId'
        name:
          type: string
        description:
          type: string
        category:
          type: string
        enabled:
          type: boolean
        address:
          $ref: '#/components/schemas/type_commons_StreetAddressShortZip'
        clinical_trials:
          type: array
          items:
            $ref: '#/components/schemas/type_clinical-trials_v1_ClinicalTrial'
      required:
      - non_insurance_payer_id
      - name
      - enabled
      - clinical_trials
      title: NonInsurancePayer
    type_write-offs_v1_WriteOffId:
      type: string
      format: uuid
      title: WriteOffId
    type_clinical-trials_v1_ClinicalTrial:
      type: object
      properties:
        name:
          type: string
        clinical_trial_number:
          type: string
          description: Must be 8 characters long
        clinical_trial_phase:
          $ref: '#/components/schemas/type_clinical-trials_v1_ClinicalTrialPhase'
        clinical_trial_id:
          $ref: '#/components/schemas/type_commons_ClinicalTrialId'
        non_insurance_payer_id:
          $ref: '#/components/schemas/type_non-insurance-payers_v1_NonInsurancePayerId'
        is_active:
          type: boolean
      required:
      - name
      - clinical_trial_number
      - clinical_trial_id
      - non_insurance_payer_id
      - is_active
      title: ClinicalTrial
    type_financials_AccountType:
      type: string
      enum:
      - PATIENT
      - INSURANCE
      - THIRD_PARTY_PAYER
      title: AccountType
    type_payers_v3_PayerUuid:
      type: string
      format: uuid
      title: PayerUuid
    type_write-offs_v1_WriteOff:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - patient
            description: 'Discriminator value: patient'
          write_off_id:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
          write_off_timestamp:
            type: string
            format: date-time
          write_off_note:
            type: string
          write_off_reason:
            $ref: '#/components/schemas/type_write-offs_v1_PatientWriteOffReason'
          patient_external_id:
            $ref: '#/components/schemas/type_commons_PatientExternalId'
          claim_id:
            $ref: '#/components/schemas/type_commons_ClaimId'
          service_line_id:
            $ref: '#/components/schemas/type_commons_ServiceLineId'
          reverts_write_off_id:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
          reverted_by_write_off_id:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
          amount_cents:
            type: integer
        required:
        - type
        - write_off_id
        - write_off_timestamp
        - write_off_reason
        - patient_external_id
        - claim_id
        - service_line_id
        - amount_cents
      - type: object
        properties:
          type:
            type: string
            enum:
            - insurance
            description: 'Discriminator value: insurance'
          write_off_id:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
          payer:
            $ref: '#/components/schemas/type_payers_v3_Payer'
          write_off_target:
            $ref: '#/components/schemas/type_write-offs_v1_InsuranceWriteOffTarget'
          write_off_timestamp:
            type: string
            format: date-time
          write_off_note:
            type: string
          write_off_reason:
            $ref: '#/components/schemas/type_write-offs_v1_InsuranceWriteOffReason'
          reverts_write_off_id:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
          reverted_by_write_off_id:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
          amount_cents:
            type: integer
        required:
        - type
        - write_off_id
        - payer
        - write_off_target
        - write_off_timestamp
        - write_off_reason
        - amount_cents
      - type: object
        properties:
          type:
            type: string
            enum:
            - non_insurance_payer
            description: 'Discriminator value: non_insurance_payer'
          write_off_id:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
          non_insurance_payer:
            $ref: '#/components/schemas/type_non-insurance-payers_v1_NonInsurancePayer'
          service_line_id:
            $ref: '#/components/schemas/type_commons_ServiceLineId'
          write_off_timestamp:
            type: string
            format: date-time
          write_off_note:
            type: string
          write_off_reason:
            $ref: '#/components/schemas/type_write-offs_v1_InsuranceWriteOffReason'
          reverts_write_off_id:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
          reverted_by_write_off_id:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOffId'
          amount_cents:
            type: integer
        required:
        - type
        - write_off_id
        - non_insurance_payer
        - service_line_id
        - write_off_timestamp
        - write_off_reason
        - amount_cents
      discriminator:
        propertyName: type
      title: WriteOff
    type_commons_AdjustmentId:
      type: string
      format: uuid
      title: AdjustmentId
    type_commons_State:
      type: string
      enum:
      - AA
      - AE
      - AP
      - AL
      - AK
      - AS
      - AZ
      - AR
      - CA
      - CO
      - CT
      - DC
      - DE
      - FL
      - FM
      - GA
      - GU
      - HI
      - ID
      - IL
      - IN
      - IA
      - KS
      - KY
      - LA
      - ME
      - MD
      - MA
      - MH
      - MI
      - MN
      - MP
      - MS
      - MO
      - MT
      - NE
      - NV
      - NH
      - NJ
      - NM
      - NY
      - NC
      - ND
      - OH
      - OK
      - OR
      - PA
      - PR
      - PW
      - RI
      - SC
      - SD
      - TN
      - TX
      - UT
      - VI
      - VT
      - VA
      - WA
      - WV
      - WI
      - WY
      title: State
    type_payers_v3_PayerIdentifier:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - payer_info
            description: 'Discriminator value: payer_info'
          payer_id:
            $ref: '#/components/schemas/type_payers_v3_PayerId'
          payer_name:
            $ref: '#/components/schemas/type_payers_v3_PayerName'
        required:
        - type
        - payer_id
        - payer_name
      - type: object
        properties:
          type:
            type: string
            enum:
            - payer_uuid
            description: 'Discriminator value: payer_uuid'
          value:
            $ref: '#/components/schemas/type_payers_v3_PayerUuid'
        required:
        - type
        - value
      discriminator:
        propertyName: type
      title: PayerIdentifier
    type_commons_StreetAddressShortZip:
      type: object
      properties:
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          $ref: '#/components/schemas/type_commons_State'
        zip_code:
          type: string
          description: 5-digit zip code
        zip_plus_four_code:
          type: string
          description: 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4
      required:
      - address1
      - city
      - state
      - zip_code
      title: StreetAddressShortZip
    type_commons_PatientExternalId:
      type: string
      title: PatientExternalId
    type_payers_v3_PayerName:
      type: string
      title: PayerName
    type_write-offs_v1_WriteOffSortField:
      type: string
      enum:
      - amount_cents
      - write_off_timestamp
      - write_off_note
      title: WriteOffSortField
    type_commons_ProviderId:
      type: string
      format: uuid
      title: ProviderId
    type_commons_SortDirection:
      type: string
      enum:
      - asc
      - desc
      title: SortDirection
    type_write-offs_v1_WriteOffsPage:
      type: object
      properties:
        prev_page_token:
          $ref: '#/components/schemas/type_commons_PageToken'
        next_page_token:
          $ref: '#/components/schemas/type_commons_PageToken'
        items:
          type: array
          items:
            $ref: '#/components/schemas/type_write-offs_v1_WriteOff'
      required:
      - items
      title: WriteOffsPage
    type_write-offs_v1_InsuranceWriteOffTarget:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - service_line_id
            description: 'Discriminator value: service_line_id'
          value:
            $ref: '#/components/schemas/type_commons_ServiceLineId'
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - claim_id
            description: 'Discriminator value: claim_id'
          value:
            $ref: '#/components/schemas/type_commons_ClaimId'
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - billing_provider_id
            description: 'Discriminator value: billing_provider_id'
          value:
            $ref: '#/components/schemas/type_commons_ProviderId'
        required:
        - type
        - value
      discriminator:
        propertyName: type
      title: InsuranceWriteOffTarget
    type_commons_StreetAddressLongZip:
      type: object
      properties:
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          $ref: '#/components/schemas/type_commons_State'
        zip_code:
          type: string
          description: 5-digit zip code
        zip_plus_four_code:
          type: string
          description: 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4
      required:
      - address1
      - city
      - state
      - zip_code
      - zip_plus_four_code
      title: StreetAddressLongZip
    type_non-insurance-payers_v1_NonInsurancePayerId:
      type: string
      format: uuid
      title: NonInsurancePayerId
    type_payers_v3_PayerId:
      type: string
      title: PayerId
    type_commons_ServiceLineId:
      type: string
      format: uuid
      title: ServiceLineId
    type_payers_v3_Payer:
      type: object
      properties:
        payer_uuid:
          $ref: '#/components/schemas/type_payers_v3_PayerUuid'
          description: Auto-generated ID set on creation.
        payer_id:
          type: string
          description: The primary national payer ID of the payer.
        payer_name:
          type: string
          description: The primary display name of the payer.
        availity_payer_name:
          type: string
          description: The name of the payer as it appears in Availity.
        availity_claims_payer_id:
          type: string
          description: The ID of the payer as it appears in Availity.
        availity_eligibility_id:
          type: string
          description: The eligibility ID of the payer as it appears in Availity.
        availity_remittance_payer_id:
          type: string
          description: The remittance ID of the payer as it appears in Availity.
        street_address:
          $ref: '#/components/schemas/type_commons_StreetAddressLongZip'
      required:
      - payer_uuid
      - payer_id
      - payer_name
      title: Payer
    type_commons_PageToken:
      type: string
      title: PageToken
    type_write-offs_v1_WriteOffCreate:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - patient
            description: 'Discriminator value: patient'
          write_off_timestamp:
            type: string
            format: date-time
          write_off_note:
            type: string
          write_off_reason:
            $ref: '#/components/schemas/type_write-offs_v1_PatientWriteOffReason'
          service_line_id:
            $ref: '#/components/schemas/type_commons_ServiceLineId'
          amount_cents:
            type: integer
        required:
        - type
        - write_off_timestamp
        - write_off_reason
        - service_line_id
        - amount_cents
      - type: object
        properties:
          type:
            type: string
            enum:
            - insurance
            description: 'Discriminator value: insurance'
          payer_identifier:
            $ref: '#/components/schemas/type_payers_v3_PayerIdentifier'
          write_off_target:
            $ref: '#/components/schemas/type_write-offs_v1_InsuranceWriteOffTarget'
          write_off_timestamp:
            type: string
            format: date-time
          write_off_note:
            type: string
          write_off_reason:
            $ref: '#/components/schemas/type_write-offs_v1_InsuranceWriteOffReason'
          amount_cents:
            type: integer
        required:
        - type
        - payer_identifier
        - write_off_target
        - write_off_timestamp
        - write_off_reason
        - amount_cents
      - type: object
        properties:
          type:
            type: string
            enum:
            - non_insurance_payer
            description: 'Discriminator value: non_insurance_payer'
          non_insurance_payer_id:
            $ref: '#/components/schemas/type_non-insurance-payers_v1_NonInsurancePayerId'
          service_line_id:
            $ref: '#/components/schemas/type_commons_ServiceLineId'
          write_off_timestamp:
            type: string
            format: date-time
          write_off_note:
            type: string
          write_off_reason:
            $ref: '#/components/schemas/type_write-offs_v1_InsuranceWriteOffReason'
          amount_cents:
            type: integer
        required:
        - type
        - non_insurance_payer_id
        - service_line_id
        - write_off_timestamp
        - write_off_reason
        - amount_cents
      discriminator:
        propertyName: type
      title: WriteOffCreate
    type_write-offs_v1_PatientWriteOffReason:
      type: string
      enum:
      - SMALL_BALANCE
      - CHARITY_OR_FINANCIAL_ASSISTANCE
      - PATIENT_EXPERIENCE_OR_SERVICE_RECOVERY
      - OON_COURTESY_ADJUSTMENT
      - PROMPT_PAY_DISCOUNT
      - BAD_DEBT
      - COLLECTION_AGENCY
      - OTHER
      - UNKNOWN
      - UNCOLLECTIBLE_OR_NON_BILLABLE
      - DECEASED
      - BANKRUPTCY
      title: PatientWriteOffReason
    type_write-offs_v1_InsuranceWriteOffReason:
      type: string
      enum:
      - SMALL_BALANCE
      - NO_AUTHORIZATION_REFERRAL
      - TIMELY_FILING
      - STALE_DATE
      - TIMELY_FILING_LATE_ENCOUNTER
      - CREDENTIALING_OR_CONTRACTING
      - NON_COVERED_MAX_BENEFIT
      - NOT_MEDICALLY_NECESSARY
      - BUNDLED_OR_INCLUSIVE
      - UNCOLLECTIBLE_OR_NON_BILLABLE
      - EFFORTS_EXHAUSTED
      - ADMINISTRATIVE_WRITE_OFF
      - CASE_RATE_OR_CAPITATED
      - OTHER
      - UNKNOWN
      - CONTRACTUAL_ADJUSTMENT
      - PRIMARY_PAID_MAX_BENEFITS
      - INTEREST
      title: InsuranceWriteOffReason
    type_commons_ClinicalTrialId:
      type: string
      format: uuid
      title: ClinicalTrialId
    type_commons_ClaimId:
      type: string
      format: uuid
      title: ClaimId
    type_clinical-trials_v1_ClinicalTrialPhase:
      type: string
      enum:
      - Phase 1
      - Phase 2
      - Phase 3
      title: ClinicalTrialPhase
  securitySchemes:
    OAuthScheme:
      type: http
      scheme: bearer
      description: OAuth 2.0 authentication