openapi: 3.0.1
info:
  title: Candid Health Auth Encounters 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: Encounters
  description: Submit and manage encounters that drive claim generation.
paths:
  /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.
components:
  schemas:
    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
    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
    BillingProvider:
      type: object
      properties:
        organization_name:
          type: string
        npi:
          type: string
        tax_id:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    EncounterPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Encounter'
        page_token:
          type: string
          nullable: true
    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'
    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'
    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
    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'
    Payer:
      type: object
      properties:
        payer_uuid:
          type: string
          format: uuid
        payer_id:
          type: string
          description: External payer / CPID identifier.
        payer_name:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OAuth bearer token obtained from POST /auth/v2/token. Send as `Authorization: Bearer <access_token>`.'