openapi: 3.0.1
info:
  title: Candid Health 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: Auth
    description: OAuth client-credentials token exchange.
  - name: Encounters
    description: Submit and manage encounters that drive claim generation.
  - name: Eligibility
    description: Real-time and batch insurance eligibility checks.
  - name: Charge Capture
    description: Capture charges and service lines ahead of claim assembly.
  - name: Payers
    description: Look up insurance payers.
  - name: Fee Schedules
    description: Resolve contracted rates for service lines.
  - name: Insurance Adjudications
    description: Retrieve ERA / 835 remittance adjudication detail.
  - name: Events
    description: Scan and retrieve billing lifecycle events.
paths:
  /auth/v2/token:
    post:
      operationId: getToken
      tags:
        - Auth
      summary: Get an OAuth bearer token.
      description: >-
        Exchange a client_id and client_secret for a short-lived JWT bearer
        access token used to authenticate all other API requests.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthGetTokenRequest'
      responses:
        '200':
          description: A bearer access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthGetTokenResponse'
        '401':
          description: Invalid client credentials.
  /encounters/v4:
    get:
      operationId: getAllEncounters
      tags:
        - Encounters
      summary: Get all encounters.
      description: Returns a paginated list of encounters matching the supplied filters.
      parameters:
        - name: limit
          in: query
          description: Maximum number of encounters to return (1-100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: page_token
          in: query
          description: Opaque cursor for the next page of results.
          schema:
            type: string
        - name: patient_external_id
          in: query
          schema:
            type: string
        - name: claim_status
          in: query
          schema:
            type: string
        - name: date_of_service_min
          in: query
          schema:
            type: string
            format: date
        - name: date_of_service_max
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: A page of encounters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncounterPage'
    post:
      operationId: createEncounter
      tags:
        - Encounters
      summary: Create a professional encounter.
      description: >-
        Creates an encounter that Candid uses to generate and submit one or more
        insurance claims.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncounterCreate'
      responses:
        '200':
          description: The created encounter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Encounter'
        '422':
          description: Validation error.
  /encounters/v4/{encounter_id}:
    get:
      operationId: getEncounter
      tags:
        - Encounters
      summary: Get an encounter.
      parameters:
        - name: encounter_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The requested encounter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Encounter'
        '404':
          description: Encounter not found.
  /eligibility/v2:
    post:
      operationId: submitEligibilityCheck
      tags:
        - Eligibility
      summary: Submit an encounter eligibility check.
      description: >-
        Runs a real-time eligibility check against a payer to confirm active
        coverage and surface patient benefit detail.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EligibilityCheckRequest'
      responses:
        '200':
          description: Eligibility result (270/271 response detail).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityCheckResponse'
  /pre-encounter/coverages/v1/check_eligibility:
    post:
      operationId: checkCoverageEligibility
      tags:
        - Eligibility
      summary: Check eligibility for a stored coverage.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EligibilityCheckRequest'
      responses:
        '200':
          description: Eligibility result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityCheckResponse'
  /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'
  /payers/v3:
    get:
      operationId: getAllPayers
      tags:
        - Payers
      summary: Get all payers.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
        - name: search_term
          in: query
          schema:
            type: string
        - name: page_token
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A page of payers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayerPage'
  /payers/v3/{payer_uuid}:
    get:
      operationId: getPayer
      tags:
        - Payers
      summary: Get a payer.
      parameters:
        - name: payer_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The requested payer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payer'
  /fee-schedules/v3/service-line/{service_line_id}/match:
    get:
      operationId: getFeeScheduleMatch
      tags:
        - Fee Schedules
      summary: Get the rate that matches a service line.
      description: >-
        Returns the fee-schedule rate matching the dimensions of a service line,
        or no result when no rate matches.
      parameters:
        - name: service_line_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The matching rate, if any.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchResult'
  /insurance_adjudications/v1/{insurance_adjudication_id}:
    get:
      operationId: getInsuranceAdjudication
      tags:
        - Insurance Adjudications
      summary: Get an insurance adjudication (ERA / remit).
      description: >-
        Returns the insurance adjudication, i.e. the 835 electronic remittance
        advice detail for a claim including payments and adjustments.
      parameters:
        - name: insurance_adjudication_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The requested insurance adjudication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsuranceAdjudication'
  /events/v1:
    get:
      operationId: scanEvents
      tags:
        - Events
      summary: Scan billing lifecycle events.
      description: >-
        Returns events ordered by modification time, used to drive webhook-style
        notifications as encounters, claims, and remits change state.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
        - name: event_types
          in: query
          schema:
            type: string
        - name: page_token
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A page of events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventPage'
  /events/v1/{event_id}:
    get:
      operationId: getEvent
      tags:
        - Events
      summary: Get an event.
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The requested event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth bearer token obtained from POST /auth/v2/token. Send as
        `Authorization: Bearer <access_token>`.
  schemas:
    AuthGetTokenRequest:
      type: object
      required:
        - client_id
        - client_secret
      properties:
        client_id:
          type: string
          description: Your application's Client ID.
        client_secret:
          type: string
          description: Your application's Client Secret.
    AuthGetTokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT bearer token.
        expires_in:
          type: integer
          description: Token lifetime in seconds.
        token_type:
          type: string
          example: Bearer
    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'
    Encounter:
      type: object
      properties:
        encounter_id:
          type: string
          format: uuid
        external_id:
          type: string
        date_of_service:
          type: string
          format: date
        patient:
          $ref: '#/components/schemas/Patient'
        billing_provider:
          $ref: '#/components/schemas/BillingProvider'
        diagnoses:
          type: array
          items:
            $ref: '#/components/schemas/Diagnosis'
        service_lines:
          type: array
          items:
            $ref: '#/components/schemas/ServiceLine'
        claims:
          type: array
          items:
            $ref: '#/components/schemas/Claim'
        status:
          type: string
        created_at:
          type: string
          format: date-time
    EncounterPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Encounter'
        page_token:
          type: string
          nullable: true
    Claim:
      type: object
      properties:
        claim_id:
          type: string
          format: uuid
        status:
          type: string
          description: Current claim processing status.
        clearinghouse_claim_id:
          type: string
          nullable: true
        payer:
          $ref: '#/components/schemas/Payer'
    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'
    BillingProvider:
      type: object
      properties:
        organization_name:
          type: string
        npi:
          type: string
        tax_id:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    RenderingProvider:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        npi:
          type: string
    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'
    ChargeCapture:
      type: object
      properties:
        charge_capture_id:
          type: string
          format: uuid
        external_id:
          type: string
        status:
          type: string
        data:
          $ref: '#/components/schemas/EncounterCreate'
    ChargeCapturePage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ChargeCapture'
        page_token:
          type: string
          nullable: true
    EligibilityCheckRequest:
      type: object
      properties:
        payer_id:
          type: string
        provider:
          $ref: '#/components/schemas/BillingProvider'
        subscriber:
          $ref: '#/components/schemas/Patient'
        service_type_codes:
          type: array
          items:
            type: string
        date_of_service:
          type: string
          format: date
    EligibilityCheckResponse:
      type: object
      properties:
        eligibility_check_id:
          type: string
          format: uuid
        active_coverage:
          type: boolean
        benefits:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              coverage_level:
                type: string
              amount_cents:
                type: integer
        raw_271:
          type: object
          description: Raw 271 eligibility response payload.
    Payer:
      type: object
      properties:
        payer_uuid:
          type: string
          format: uuid
        payer_id:
          type: string
          description: External payer / CPID identifier.
        payer_name:
          type: string
    PayerPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Payer'
        page_token:
          type: string
          nullable: true
    MatchResult:
      type: object
      properties:
        rate_id:
          type: string
          format: uuid
        rate_cents:
          type: integer
        matched:
          type: boolean
    InsuranceAdjudication:
      type: object
      description: 835 electronic remittance advice (ERA) detail.
      properties:
        insurance_adjudication_id:
          type: string
          format: uuid
        payer:
          $ref: '#/components/schemas/Payer'
        claims:
          type: array
          items:
            type: object
            properties:
              claim_id:
                type: string
                format: uuid
              paid_amount_cents:
                type: integer
              adjustments:
                type: array
                items:
                  type: object
                  properties:
                    group_code:
                      type: string
                    reason_code:
                      type: string
                    amount_cents:
                      type: integer
        check_number:
          type: string
        paid_date:
          type: string
          format: date
    Event:
      type: object
      properties:
        event_id:
          type: string
          format: uuid
        event_type:
          type: string
          description: e.g. claim.updated, encounter.created, remit.received.
        resource_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        data:
          type: object
    EventPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        page_token:
          type: string
          nullable: true
    Address:
      type: object
      properties:
        address1:
          type: string
        address2:
          type: string
          nullable: true
        city:
          type: string
        state:
          type: string
        zip_code:
          type: string