openapi: 3.1.0
info:
  title: API Reference subpackage_auth.subpackage_auth/default subpackage_fee-schedules.subpackage_fee-schedules/v3 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: subpackage_fee-schedules.subpackage_fee-schedules/v3
paths:
  /api/fee-schedules/v3/service-line/{service_line_id}/match:
    get:
      operationId: get-match
      summary: Get Match
      description: Gets the rate that matches a service line.  No result means no rate exists matching the service line's dimensions.
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: service_line_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:ServiceLineId'
      - 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_fee-schedules/v3:MatchResult'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - EntityNotFoundError
                  content:
                    $ref: '#/components/schemas/type_commons:EntityNotFoundErrorMessage'
                required:
                - errorName
                - content
        '422':
          description: Error response with status 422
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - FailedToBuildServiceLineDimensions
                  content:
                    $ref: '#/components/schemas/type_commons:ErrorMessage'
                required:
                - errorName
                - content
  /api/fee-schedules/v3/service-line/{service_line_id}/match/{rate_id}:
    get:
      operationId: test-match
      summary: Test Match
      description: Tests a service line against a rate to see if it matches.
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: service_line_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:ServiceLineId'
      - name: rate_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:RateId'
      - 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_fee-schedules/v3:MatchTestResult'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - EntityNotFoundError
                  content:
                    $ref: '#/components/schemas/type_commons:EntityNotFoundErrorMessage'
                required:
                - errorName
                - content
        '422':
          description: Error response with status 422
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - FailedToBuildServiceLineDimensions
                  content:
                    $ref: '#/components/schemas/type_commons:ErrorMessage'
                required:
                - errorName
                - content
  /api/fee-schedules/v3:
    get:
      operationId: get-multi
      summary: Get Multi
      description: Gets a list of dimensions with their rates. The rates returned will always be the most recent versions of those rates.
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: page_token
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:PageToken'
      - name: limit
        in: query
        description: Max number of dimensions returned. Defaults to 100. Max is 100.
        required: false
        schema:
          type: integer
      - name: active_date
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: payer_uuid
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_payers/v3:PayerUuid'
      - name: organization_billing_provider_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_organization-providers/v2:OrganizationProviderId'
      - name: states
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:State'
      - name: zip_codes
        in: query
        required: false
        schema:
          type: string
      - name: license_types
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_organization-providers/v2:LicenseType'
      - name: facility_type_codes
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FacilityTypeCode'
      - name: network_types
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:NetworkType'
      - name: payer_plan_group_ids
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:PayerPlanGroupId'
      - name: cpt_code
        in: query
        required: false
        schema:
          type: string
      - name: modifiers
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:ProcedureModifier'
      - 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_fee-schedules/v3:RatesPage'
    post:
      operationId: upload-fee-schedule
      summary: Upload a fee schedule (a collection of rates)
      description: 'Uploads a new fee schedule.


        Each rate may either be totally new as qualified by it''s dimensions or a new version for an existing rate.


        If adding a new version to an existing rate, the rate must be posted with the next version number (previous version + 1) or a EntityConflictError will

        be returned.


        Use the dry run flag to discover already existing rates and to run validations.  If validations for any rate fail, no rates will

        be saved to the system.'
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/type_fee-schedules/v3:Rate'
        '422':
          description: Error response with status 422
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - FeeScheduleValidationHttpError
                  content:
                    type: array
                    items:
                      $ref: '#/components/schemas/type_fee-schedules/v3:RateUploadWithPossibleErrors'
                required:
                - errorName
                - content
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dry_run:
                  type: boolean
                rates:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_fee-schedules/v3:RateUpload'
              required:
              - dry_run
              - rates
  /api/fee-schedules/v3/unique-dimension-values:
    get:
      operationId: get-unique-values-for-dimension
      summary: Get Unique Values For Dimension
      description: Gets unique values for a dimension based on other selection criteria. The response is a list of dimensions with your criteria and the unique values populated. This API is useful for driving pivots on dimension values.
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: page_token
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:PageToken'
      - name: limit
        in: query
        description: Max number of values returned. Defaults to 1000. Max is 1000.
        required: false
        schema:
          type: integer
      - name: pivot_dimension
        in: query
        description: The name of the dimension to fetch unique values for.
        required: true
        schema:
          $ref: '#/components/schemas/type_fee-schedules/v3:DimensionName'
      - name: payer_uuid
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_payers/v3:PayerUuid'
      - name: organization_billing_provider_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_organization-providers/v2:OrganizationProviderId'
      - name: states
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:State'
      - name: zip_codes
        in: query
        required: false
        schema:
          type: string
      - name: license_types
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_organization-providers/v2:LicenseType'
      - name: facility_type_codes
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FacilityTypeCode'
      - name: network_types
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:NetworkType'
      - name: payer_plan_group_ids
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:PayerPlanGroupId'
      - name: cpt_code
        in: query
        required: false
        schema:
          type: string
      - name: modifiers
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:ProcedureModifier'
      - 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_fee-schedules/v3:DimensionsPage'
  /api/fee-schedules/v3/{rate_id}/history:
    get:
      operationId: get-rate-history
      summary: Get Rate History
      description: Gets every version of a rate.
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: rate_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:RateId'
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/type_fee-schedules/v3:Rate'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - EntityNotFoundError
                  content:
                    $ref: '#/components/schemas/type_commons:EntityNotFoundErrorMessage'
                required:
                - errorName
                - content
  /api/fee-schedules/v3/{rate_id}/{version}:
    delete:
      operationId: delete-rate
      summary: Delete a rate
      description: Soft deletes a rate from the system.  Only the most recent version of a rate can be deleted.
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: rate_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:RateId'
      - name: version
        in: path
        required: true
        schema:
          type: integer
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - EntityNotFoundError
                  content:
                    $ref: '#/components/schemas/type_commons:EntityNotFoundErrorMessage'
                required:
                - errorName
                - content
        '409':
          description: Error response with status 409
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - EntityConflictError
                  content:
                    $ref: '#/components/schemas/type_commons:EntityConflictErrorMessage'
                required:
                - errorName
                - content
  /api/fee-schedules/v3/payer-threshold/default:
    get:
      operationId: get-payer-thresholds-default
      summary: Get Payer Thresholds Default
      description: Gets the default payer threshold
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      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_fee-schedules/v3:PayerThreshold'
  /api/fee-schedules/v3/payer-threshold:
    get:
      operationId: get-payer-thresholds
      summary: Get Payer Thresholds
      description: Gets a list of payers and thresholds by their uuids
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: payer_uuids
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/type_payers/v3:PayerUuid'
      - 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_fee-schedules/v3:PayerThresholdsPage'
  /api/fee-schedules/v3/payer-threshold/{payer_uuid}:
    put:
      operationId: set-payer-threshold
      summary: Set Payer Threshold
      description: Sets the threshold information for a payer
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: payer_uuid
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_payers/v3:PayerUuid'
      - 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_fee-schedules/v3:PayerThreshold'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - EntityNotFoundError
                  content:
                    $ref: '#/components/schemas/type_commons:EntityNotFoundErrorMessage'
                required:
                - errorName
                - content
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_fee-schedules/v3:PayerThreshold'
  /api/fee-schedules/v3/hard-delete:
    post:
      operationId: hard-delete-rates
      summary: Hard delete rates
      description: Hard deletes rates from the system that match the provided dimensions.  This is a destructive operation and cannot be undone.  If an empty dimensions object is provided, all rates will be hard deleted.  The maximum number of rates this API will delete at a time is 10000.  Returns the number of rates deleted and if that number is the maximum, the caller should call this API again to continue deleting rates.
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_fee-schedules/v3:OptionalDimensions'
  /api/fee-schedules/v3/hard-delete-by-ids:
    post:
      operationId: hard-delete-rates-by-ids
      summary: Hard delete rates by IDs
      description: Hard deletes specific rates from the system by their IDs. This is a destructive operation and cannot be undone. Limited to 100 rate IDs maximum per request. For bulk deletion of more than 100 rates, use the hard_delete_rates endpoint with dimension filters. Returns the number of rates deleted.
      tags:
      - subpackage_fee-schedules.subpackage_fee-schedules/v3
      parameters:
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rate_ids:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_commons:RateId'
              required:
              - rate_ids
components:
  schemas:
    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_commons:EntityConflictErrorMessage:
      type: object
      properties:
        entity_name:
          type: string
      required:
      - entity_name
      title: EntityConflictErrorMessage
    type_commons:EntityNotFoundErrorMessage:
      type: object
      properties:
        id:
          type: string
      required:
      - id
      title: EntityNotFoundErrorMessage
    type_commons:PageToken:
      type: string
      title: PageToken
    type_commons:PayerPlanGroupId:
      type: string
      format: uuid
      title: PayerPlanGroupId
    type_commons:NetworkType:
      type: string
      enum:
      - '12'
      - '13'
      - '14'
      - '15'
      - '16'
      - '17'
      - AM
      - CH
      - DS
      - HM
      - LM
      - MA
      - MB
      - MC
      - OF
      - TV
      - VA
      - WC
      - ZZ
      - CI
      - BL
      title: NetworkType
    type_commons:ErrorMessage:
      type: string
      title: ErrorMessage
    type_commons:ProcedureModifier:
      type: string
      enum:
      - AV
      - AU
      - AW
      - AY
      - '07'
      - 08
      - 09
      - '10'
      - '11'
      - '12'
      - '13'
      - '14'
      - '15'
      - '16'
      - '22'
      - '23'
      - '24'
      - '25'
      - '26'
      - '27'
      - '28'
      - '32'
      - '33'
      - '47'
      - '50'
      - '51'
      - '52'
      - '53'
      - '54'
      - '55'
      - '56'
      - '57'
      - '58'
      - '59'
      - '62'
      - '63'
      - '66'
      - '74'
      - '76'
      - '77'
      - '78'
      - '79'
      - '80'
      - '81'
      - '82'
      - '90'
      - '91'
      - '92'
      - '93'
      - '95'
      - '96'
      - '97'
      - '99'
      - A1
      - A2
      - A3
      - A4
      - A5
      - A6
      - A7
      - A8
      - A9
      - AA
      - AB
      - AD
      - AE
      - AF
      - AG
      - AH
      - AI
      - AJ
      - AK
      - AM
      - AO
      - AP
      - AQ
      - AR
      - AS
      - AT
      - AZ
      - BA
      - BL
      - BO
      - BP
      - BR
      - BU
      - CA
      - CB
      - CC
      - CD
      - CE
      - CF
      - CG
      - CH
      - CI
      - CJ
      - CK
      - CL
      - CM
      - CN
      - CR
      - CS
      - CT
      - CO
      - CQ
      - DA
      - E1
      - E2
      - E3
      - E4
      - EA
      - EB
      - EC
      - ED
      - EE
      - EJ
      - EM
      - EP
      - ER
      - ET
      - EV
      - EX
      - EY
      - F1
      - F2
      - F3
      - F4
      - F5
      - F6
      - F7
      - F8
      - F9
      - FA
      - FB
      - FC
      - FP
      - FQ
      - FR
      - FS
      - FT
      - FX
      - FY
      - G0
      - G1
      - G2
      - G3
      - G4
      - G5
      - G6
      - G7
      - G8
      - G9
      - GA
      - GB
      - GC
      - GE
      - GF
      - GG
      - GH
      - GJ
      - GK
      - GL
      - GM
      - GN
      - GO
      - GP
      - GQ
      - GR
      - GS
      - GT
      - GU
      - GV
      - GW
      - GX
      - GY
      - GZ
      - HA
      - HB
      - HC
      - HD
      - HE
      - HF
      - HG
      - HH
      - HI
      - HJ
      - HK
      - HL
      - HM
      - HN
      - HO
      - HP
      - HQ
      - HR
      - HS
      - HT
      - HU
      - HV
      - HW
      - HX
      - HY
      - HZ
      - J1
      - J2
      - J3
      - J4
      - J5
      - JA
      - JB
      - JC
      - JD
      - JE
      - JG
      - JW
      - JZ
      - K0
      - K1
      - K2
      - K3
      - K4
      - KA
      - KB
      - KC
      - KD
      - KE
      - KF
      - KG
      - KH
      - KI
      - KJ
      - KK
      - KL
      - KM
      - KN
      - KO
      - KP
      - KQ
      - KR
      - KS
      - KT
      - KU
      - KV
      - KW
      - KX
      - KY
      - KZ
      - LC
      - LD
      - LL
      - LM
      - LR
      - LS
      - LT
      - LU
      - M2
      - MA
      - MB
      - MC
      - MD
      - ME
      - MF
      - MG
      - MH
      - MS
      - N1
      - N2
      - N3
      - NB
      - NR
      - NU
      - P1
      - P2
      - P3
      - P4
      - P5
      - P6
      - PA
      - PB
      - PC
      - PD
      - PI
      - PL
      - PM
      - PN
      - PO
      - PS
      - PT
      - Q0
      - Q1
      - Q2
      - Q3
      - Q4
      - Q5
      - Q6
      - Q7
      - Q8
      - Q9
      - QA
      - QB
      - QC
      - QD
      - QE
      - QF
      - QG
      - QH
      - QJ
      - QK
      - QL
      - QM
      - QN
      - QP
      - QQ
      - QR
      - QS
      - QT
      - QW
      - QX
      - QY
      - QZ
      - RA
      - RB
      - RC
      - RD
      - RE
      - RI
      - RR
      - RT
      - SA
      - SB
      - SC
      - SD
      - SE
      - SF
      - SG
      - SH
      - SJ
      - SL
      - SM
      - SN
      - SQ
      - SS
      - ST
      - SU
      - SV
      - SW
      - SY
      - T1
      - T2
      - T3
      - T4
      - T5
      - T6
      - T7
      - T8
      - T9
      - TA
      - TB
      - TC
      - TD
      - TE
      - TF
      - TG
      - TH
      - TJ
      - TK
      - TL
      - TM
      - TN
      - TP
      - TQ
      - TR
      - TS
      - TT
      - TU
      - TV
      - TW
      - U1
      - U2
      - U3
      - U4
      - U5
      - U6
      - U7
      - U8
      - U9
      - UA
      - UB
      - UC
      - UD
      - UE
      - UF
      - UG
      - UH
      - UJ
      - UK
      - UN
      - UP
      - UQ
      - UR
      - US
      - V1
      - V2
      - V3
      - W1
      - W2
      - W3
      - X4
      - XE
      - XP
      - XS
      - XU
      - XY
      - ZZ
      title: ProcedureModifier
    type_commons:FacilityTypeCode:
      type: string
      enum:
      - '01'
      - '02'
      - '03'
      - '04'
      - '05'
      - '06'
      - '07'
      - 08
      - 09
      - '10'
      - '11'
      - '12'
      - '13'
      - '14'
      - '15'
      - '16'
      - '17'
      - '18'
      - '19'
      - '20'
      - '21'
      - '22'
      - '23'
      - '24'
      - '25'
      - '26'
      - '31'
      - '32'
      - '33'
      - '34'
      - '41'
      - '42'
      - '49'
      - '50'
      - '51'
      - '52'
      - '53'
      - '54'
      - '55'
      - '56'
      - '57'
      - '58'
      - '60'
      - '61'
      - '62'
      - '65'
      - '71'
      - '72'
      - '81'
      - '99'
      description: 'Box 24B on the CMS-1500 claim form. Line-level place of service is not currently supported.

        02 for telemedicine, 11 for in-person. Full list here:

        https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set'
      title: FacilityTypeCode
    type_commons:RateId:
      type: string
      format: uuid
      title: RateId
    type_commons:ServiceLineId:
      type: string
      format: uuid
      title: ServiceLineId
  securitySchemes:
    OAuthScheme:
      type: http
      scheme: bearer
      description: OAuth 2.0 authentication