openapi: 3.0.1
info:
  title: Candid Health Auth Charge Capture API
  description: REST API for Candid Health, an autonomous medical-billing and revenue-cycle management platform. Submit encounters and claims, run eligibility checks, capture charges, look up payers and fee schedules, retrieve insurance adjudications (ERAs / remits), and scan billing lifecycle events. All requests are authenticated with an OAuth bearer token obtained from the auth token endpoint.
  termsOfService: https://www.joincandidhealth.com
  contact:
    name: Candid Health Support
    url: https://docs.joincandidhealth.com/additional-resources/support
  version: '1.0'
servers:
- url: https://api.joincandidhealth.com/api
  description: Candid Health production API
security:
- bearerAuth: []
tags:
- name: Charge Capture
  description: Capture charges and service lines ahead of claim assembly.
paths:
  /charge_captures/v1:
    post:
      operationId: createChargeCapture
      tags:
      - Charge Capture
      summary: Create a charge capture.
      description: Captures a charge with diagnoses and service lines that later bundles into an encounter for claim assembly.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChargeCaptureCreate'
      responses:
        '200':
          description: The created charge capture.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeCapture'
    get:
      operationId: getAllChargeCaptures
      tags:
      - Charge Capture
      summary: Get all charge captures.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
      - name: page_token
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A page of charge captures.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeCapturePage'
  /charge_captures/v1/{charge_capture_id}:
    get:
      operationId: getChargeCapture
      tags:
      - Charge Capture
      summary: Get a charge capture.
      parameters:
      - name: charge_capture_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The requested charge capture.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeCapture'
components:
  schemas:
    ChargeCapturePage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ChargeCapture'
        page_token:
          type: string
          nullable: true
    ChargeCapture:
      type: object
      properties:
        charge_capture_id:
          type: string
          format: uuid
        external_id:
          type: string
        status:
          type: string
        data:
          $ref: '#/components/schemas/EncounterCreate'
    Address:
      type: object
      properties:
        address1:
          type: string
        address2:
          type: string
          nullable: true
        city:
          type: string
        state:
          type: string
        zip_code:
          type: string
    RenderingProvider:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        npi:
          type: string
    BillingProvider:
      type: object
      properties:
        organization_name:
          type: string
        npi:
          type: string
        tax_id:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    Patient:
      type: object
      properties:
        external_id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
          format: date
        gender:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    EncounterCreate:
      type: object
      required:
      - external_id
      - patient_authorized_release
      - benefits_assigned_to_provider
      - provider_accepts_assignment
      - billable_status
      - patient
      - responsible_party
      - billing_provider
      - diagnoses
      - place_of_service_code
      properties:
        external_id:
          type: string
          description: Client-specified unique identifier for the encounter.
        patient_authorized_release:
          type: boolean
        benefits_assigned_to_provider:
          type: boolean
        provider_accepts_assignment:
          type: boolean
        billable_status:
          type: string
          enum:
          - BILLABLE
          - NOT_BILLABLE
        responsible_party:
          type: string
          enum:
          - INSURANCE_PAY
          - SELF_PAY
          - UNKNOWN
        date_of_service:
          type: string
          format: date
        place_of_service_code:
          type: string
          description: Place of service code, e.g. "02" for telehealth.
        patient:
          $ref: '#/components/schemas/Patient'
        billing_provider:
          $ref: '#/components/schemas/BillingProvider'
        rendering_provider:
          $ref: '#/components/schemas/RenderingProvider'
        diagnoses:
          type: array
          items:
            $ref: '#/components/schemas/Diagnosis'
        service_lines:
          type: array
          items:
            $ref: '#/components/schemas/ServiceLine'
    Diagnosis:
      type: object
      properties:
        code_type:
          type: string
          example: ABK
        code:
          type: string
          description: ICD-10 diagnosis code.
    ServiceLine:
      type: object
      properties:
        service_line_id:
          type: string
          format: uuid
        procedure_code:
          type: string
          description: CPT / HCPCS procedure code.
        quantity:
          type: string
        charge_amount_cents:
          type: integer
        diagnosis_pointers:
          type: array
          items:
            type: integer
        date_of_service:
          type: string
          format: date
    ChargeCaptureCreate:
      type: object
      required:
      - external_id
      - data
      properties:
        external_id:
          type: string
        status:
          type: string
        data:
          $ref: '#/components/schemas/EncounterCreate'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OAuth bearer token obtained from POST /auth/v2/token. Send as `Authorization: Bearer <access_token>`.'