Circle V2 API Docs
    Preparing search index...

    Class KipuApiClient

    Kipu API Client

    Object-oriented wrapper for Kipu API interactions. Encapsulates credentials and provides methods for all API operations.

    const client = new KipuApiClient({
    access_id: "your_access_id",
    secret_key: "your_secret_key",
    app_id: "your_app_id"
    });

    const admissions = await client.getAdmissions("2025-01-01", "2025-01-27");
    Index

    Constructors

    Methods

    • Fetch admissions within a date range

      Parameters

      • startDate: string
      • endDate: string
      • phi_level: "high" | "medium" | "low" = 'low'
      • Optionalinsurance_detail: "v121"

      Returns Promise<
          {
              address_city: string
              | null;
              address_country?: string;
              address_street: string | null;
              address_street2: string | null;
              address_zip: string | null;
              admission_date: string;
              alternate_addresses: {
                  city?: string | null;
                  country?: string | null;
                  state?: string | null;
                  street1?: string | null;
                  street2?: string | null;
                  zip?: string | null;
              }[];
              alternate_phone?: string;
              anticipated_discharge_date: string
              | null;
              bed_name: string | null;
              building_name: string | null;
              casefile_id: string;
              cause_of_death: string | null;
              created_at: string;
              date_of_death: string | null;
              diagnosis_codes: string | null;
              discharge_date: string | null;
              discharge_or_transition_id: number | null;
              discharge_or_transition_name: string | null;
              discharge_type: string | null;
              discharge_type_code: string | null;
              dob: string;
              email?: string;
              ethnicity: string | null;
              ext_id_mappings?: { ext_id?: string; ext_system_name?: string }[];
              external_apps: {
                  external_app_name?: string;
                  external_app_patient_id?: string;
              }[];
              first_contact_date?: string;
              first_contact_information?: string
              | null;
              first_contact_name: string | null;
              first_contact_relationship?: string | null;
              first_contact_rep_on_call?: string | null;
              first_name: string;
              gender?: string;
              gender_identity?: string;
              insurance_company: string | null;
              insurances?: {
                  effective_date?: string;
                  ext_payor_id?: string;
                  group_ID?: string;
                  group_plan_name?: string;
                  insurance_company?: string;
                  insurance_phone?: string;
                  insurance_plan_period?: string;
                  insurance_plan_type?: string;
                  insurance_priority?: string;
                  notes?: string | null;
                  payor_type?: string;
                  policy_no?: string;
                  status?: string;
                  subscriber_address_city?: string | null;
                  subscriber_address_country?: string | null;
                  subscriber_address_state?: string | null;
                  subscriber_address_street?: string | null;
                  subscriber_address_street2?: string | null;
                  subscriber_address_zip?: string | null;
                  subscriber_DOB?: string;
                  subscriber_first_name?: string;
                  subscriber_gender?: string | null;
                  subscriber_last_name?: string;
                  subscriber_relationship?: string;
                  subscriber_SSN?: string;
                  termination_date?: string;
              }[];
              last_name: string;
              last_updated_at: string;
              level_of_care: string
              | null;
              location_id: number | null;
              location_name: string | null;
              maiden_name: string | null;
              middle_name: string;
              mr_number: string | null;
              next_level_of_care: string | null;
              next_level_of_care_date: string | null;
              patient_contacts?: {
                  address?: string | null;
                  alternative_phone?: string | null;
                  contact_type?: string | null;
                  email?: string | null;
                  full_name?: string | null;
                  notes?: string | null;
                  phone?: string | null;
                  relationship?: string | null;
              }[];
              patient_statuses?: {
                  end_date?: string;
                  name?: string;
                  start_date?: string;
                  value?: string
                  | null;
              }[];
              patient_tags: { color: string; id: number; name: string }[];
              payment_method: string | null;
              payment_method_category: string | null;
              phone: string | null;
              pre_admission_status: string | null;
              pre_admission_status_id?: string | null;
              preferred_contact: string | null;
              preferred_language: string | null;
              preferred_name?: string | null;
              program: string | null;
              pronouns: string | null;
              race: string | null;
              record_source: string;
              referrer_name: string | null;
              room_name: string | null;
              sobriety_date?: string | null;
              ssn?: string;
              state: string | null;
          }[],
      >

    • Type Parameters

      • T extends { pagination?: { total_pages: string } }

      Parameters

      • getPage: (page: number, pageSize: number) => Promise<T>

      Returns Promise<T[]>

    • Returns Promise<
          Safe<
              {
                  email: string;
                  first_name: string;
                  home_phone: string;
                  id: string;
                  last_name: string;
                  middle_name: string;
                  mobile: string;
                  title: string;
              }[],
          >,
      >

    • Parameters

      • appointmentId: number

      Returns Promise<
          {
              all_day: boolean;
              appointment_type: string;
              billable: boolean;
              end_time: string;
              id: number;
              notes: string;
              recurrences?: {
                  all_day: boolean;
                  appointment_type: string;
                  billable: boolean;
                  end_time: string;
                  id: number;
                  notes: string;
                  start_time: string;
                  status: string;
                  subject: string;
              }[];
              recurring?: boolean;
              scheduled_ext_providers: {
                  address: {
                      city: string;
                      state: string;
                      street1: string;
                      street2: string;
                      zip: string;
                  };
                  company_website: string;
                  fax: string;
                  name: string;
                  phone: string;
              }[];
              scheduled_patients: {
                  casefile_id: string;
                  email: string;
                  full_name: string;
              }[];
              scheduled_providers: {
                  email: string;
                  full_name: string;
                  id: string;
                  provider_title: string;
              }[];
              start_time: string;
              status: string;
              subject: string;
          },
      >

    • Fetch all care levels (v4) — the catalog of clinical LOCs configured for the account.

      Returns Promise<
          {
              billable?: string;
              care_level_id: number;
              care_level_name: string;
              claim_format?: string;
              consider_as?: string;
              days_of_the_week?: {
                  fri?: string;
                  mon?: string;
                  sat?: string;
                  sun?: string;
                  thu?: string;
                  tue?: string;
                  wed?: string;
              };
              hours?: string;
              locations?: { id?: number; name?: string }[];
              occurrence_code?: string;
              occurrence_span_code?: string;
              place_of_service?: string;
              selected_billing_code?: {
                  CCode?: string;
                  Custom?: string;
                  HCode?: string;
                  RCode?: string;
              };
              type_of_bill?: string;
              value_code?: string;
          }[],
      >

    • Get the API credentials currently being used by this client

      Returns KipuCredentials

      Current access ID and secret key

    • Parameters

      • casefileId: string

      Returns Promise<
          {
              diagnosis: string
              | null;
              logged_at: string | null;
              logged_by: string | null;
              start_date: string | null;
          }[],
      >

    • Fetch digital signatures for a patient evaluation

      Parameters

      • evaluationId: number

        Evaluation ID to fetch signatures for

      Returns Promise<KipuEvaluationSignature[]>

      Array of signatures with user information and timestamps

    • Fetch evaluation template structure and configuration

      Parameters

      • evaluationId: number

        Template ID to fetch

      Returns Promise<unknown>

      Template configuration with sections and items

    • Fetch patient glucose monitoring logs

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              evaluation_timestamp: string;
              id: number;
              intervention: string[];
              note: string;
              patient_id: number;
              reading: number;
              type_of_check: string;
              user_name: string;
          }[],
      >

      Array of glucose readings with timestamps and interventions

    • Fetch all facility locations

      Returns Promise<
          {
              buildings?: {
                  building_id?: number;
                  building_name?: string;
                  enabled?: boolean;
              }[];
              enabled: boolean;
              location_id: number;
              location_name: string;
          }[],
      >

      Array of location records with facility information

    • Fetch patient orthostatic vital signs (lying, sitting, standing positions)

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              blood_pressure_diastolic_lying: number;
              blood_pressure_diastolic_sitting: number;
              blood_pressure_diastolic_standing: number;
              blood_pressure_systolic_lying: number;
              blood_pressure_systolic_sitting: number;
              blood_pressure_systolic_standing: number;
              comments: string;
              id: number;
              interval_timestamp: string;
              o2_saturation: number;
              patient_id: number;
              pulse_lying: number;
              pulse_sitting: number;
              pulse_standing: number;
              respirations: number;
              temperature: number;
              user_name: string;
          }[],
      >

      Array of orthostatic vital sign measurements

    • Fetch patient demographic and program history details

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              address_city: string
              | null;
              address_country?: string;
              address_street: string | null;
              address_street2: string | null;
              address_zip: string | null;
              admission_date: string;
              alternate_addresses: {
                  city?: string | null;
                  country?: string | null;
                  state?: string | null;
                  street1?: string | null;
                  street2?: string | null;
                  zip?: string | null;
              }[];
              alternate_phone?: string;
              anticipated_discharge_date: string
              | null;
              bed_name: string | null;
              building_name: string | null;
              casefile_id: string;
              cause_of_death: string | null;
              created_at: string;
              date_of_death: string | null;
              diagnosis_codes: string | null;
              discharge_date: string | null;
              discharge_or_transition_id: number | null;
              discharge_or_transition_name: string | null;
              discharge_type: string | null;
              discharge_type_code: string | null;
              dob: string;
              email?: string;
              ethnicity: string | null;
              ext_id_mappings?: {
                  ext_id?: string;
                  ext_system_name?: string;
                  id?: string;
              }[];
              external_apps: {
                  external_app_name?: string;
                  external_app_patient_id?: string;
                  id?: string;
              }[];
              first_contact_date?: string;
              first_contact_information?: string
              | null;
              first_contact_name: string | null;
              first_contact_relationship?: string | null;
              first_contact_rep_on_call?: string | null;
              first_name: string;
              gender?: string;
              gender_identity?: string;
              insurance_company: string | null;
              insurances?: {
                  effective_date?: string;
                  ext_payor_id?: string;
                  group_ID?: string;
                  group_plan_name?: string;
                  id?: string;
                  insurance_company?: string;
                  insurance_phone?: string;
                  insurance_plan_period?: string;
                  insurance_plan_type?: string;
                  insurance_priority?: string;
                  notes?: string | null;
                  payor_type?: string;
                  policy_no?: string;
                  status?: string;
                  subscriber_address_city?: string | null;
                  subscriber_address_country?: string | null;
                  subscriber_address_state?: string | null;
                  subscriber_address_street?: string | null;
                  subscriber_address_street2?: string | null;
                  subscriber_address_zip?: string | null;
                  subscriber_DOB?: string;
                  subscriber_first_name?: string;
                  subscriber_gender?: string | null;
                  subscriber_last_name?: string;
                  subscriber_relationship?: string;
                  subscriber_SSN?: string;
                  termination_date?: string;
              }[];
              last_name: string;
              last_updated_at: string;
              level_of_care: string
              | null;
              location_id: number | null;
              location_name: string | null;
              maiden_name: string;
              middle_name: string;
              mr_number: string | null;
              next_level_of_care: string | null;
              next_level_of_care_date: string | null;
              patient_contacts?: {
                  address?: string | null;
                  alternative_phone?: string | null;
                  contact_type?: string | null;
                  email?: string | null;
                  full_name?: string | null;
                  notes?: string | null;
                  phone?: string | null;
                  relationship?: string | null;
              }[];
              patient_statuses?: {
                  end_date?: string;
                  name?: string;
                  start_date?: string;
                  value?: string
                  | null;
              }[];
              patient_tags: { color: string; id: number; name: string }[];
              payment_method: string | null;
              payment_method_category: string | null;
              phone: string | null;
              pre_admission_status: string | null;
              pre_admission_status_id?: string | null;
              preferred_contact: string;
              preferred_language: string | null;
              preferred_name?: string | null;
              program: string | null;
              pronouns: string | null;
              race: string | null;
              record_source: string;
              referrer_name: string | null;
              room_name: string | null;
              sobriety_date?: string | null;
              ssn?: string;
              state: string | null;
          },
      >

      Patient object with demographic and program information

    • Parameters

      • casefileId: string

      Returns Promise<
          {
              all_day?: boolean;
              appointment_type?: string;
              billable?: boolean;
              end_time?: string;
              id?: number;
              recurring?: boolean;
              start_time?: string;
              status?: string;
              subject?: string;
              upcoming_dates?: string[];
          }[],
      >

    • Fetch patient care team members (providers, case managers, etc.)

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          | {
              care_team_case_manager: string;
              care_team_case_manager_assign_date: string
              | null;
              care_team_nurse: string;
              care_team_nurse_assign_date: string | null;
              care_team_physician: string;
              care_team_physician_assign_date: string | null;
              care_team_therapist: string;
              care_team_therapist_assign_date: string | null;
          }
          | undefined,
      >

      Care team information or undefined if not found

    • Fetch CIWA-Ar (Alcohol Withdrawal) assessments

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              agitation: number;
              agitation_label: string;
              anxiety: number;
              anxiety_label: string;
              auditory_disturbances: number;
              auditory_disturbances_label: string;
              clouding_of_sensorium: number;
              clouding_of_sensorium_label: string;
              headache: number;
              headache_label: string;
              id: number;
              interval: string;
              interval_label: string;
              nausea: number;
              nausea_label: string;
              paroxysmal_sweats: number;
              paroxysmal_sweats_label: string;
              patient_id: number;
              score: number;
              tactile_disturbances: number;
              tactile_disturbances_label: string;
              tremor: number;
              tremor_label: string;
              username: string;
              visual_disturbances: number;
              visual_disturbances_label: string;
          }[],
      >

      Array of CIWA-Ar assessment records

    • Fetch CIWA-B (Benzodiazepine Withdrawal) assessments

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              anxiety: number;
              anxiety_label: string;
              difficulty_concentrating: number;
              difficulty_concentrating_label: string;
              enough_sleep: number;
              enough_sleep_label: string;
              fatigued: number;
              fatigued_label: string;
              fearful: number;
              fearful_label: string;
              feel_palms: number;
              feel_palms_label: string;
              head_full_achy: number;
              head_full_achy_label: string;
              heart_racing: number;
              heart_racing_label: string;
              id: number;
              interval: string;
              interval_label: string;
              irritable: number;
              irritable_label: string;
              loss_of_appetite: number;
              loss_of_appetite_label: string;
              muscle_ache: number;
              muscle_ache_label: string;
              numbness: number;
              numbness_label: string;
              patient_id: number;
              possible_misfortunes: number;
              possible_misfortunes_label: string;
              restful_sleep: number;
              restful_sleep_label: string;
              score: number;
              sweating_agitation: number;
              sweating_agitation_label: string;
              tensed: number;
              tensed_label: string;
              tremors: number;
              tremors_label: string;
              upset: number;
              upset_label: string;
              username: string;
              visual_disturbances: number;
              visual_disturbances_label: string;
              weakness: number;
              weakness_label: string;
          }[],
      >

      Array of CIWA-B assessment records

    • Fetch patient consent form records

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              consent_form_records: {
                  complete: boolean;
                  consent_form_id: number;
                  expiration_date: string
                  | null;
                  expired: boolean;
                  expires: boolean;
                  id: number;
                  name: string;
                  patient_casefile_id: string;
              }[];
              pagination: {
                  current_page: string;
                  records_per_page: string;
                  total_pages: string;
                  total_records: string;
              };
          },
      >

      All consent forms signed by the patient

    • Fetch patient COWS (Clinical Opiate Withdrawal Scale) assessments

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<Record<string, never>[]>

      Array of COWS assessment records

    • Fetch detailed patient evaluation including all items and responses

      Parameters

      • evaluationId: number

        Evaluation ID to fetch

      Returns Promise<PatientEvaluationDetails>

      Evaluation details with all nested items and settings

    • Fetch patient evaluation details with digital signatures

      Combines evaluation details with signature data

      Parameters

      • evaluationId: number

        Evaluation ID to fetch

      Returns Promise<PatientEvaluationDetailsWithSignatures>

      Evaluation details with embedded signature array

    • Parameters

      • casefileId: string
      • options: { completed_only?: boolean; current_census_only?: boolean } = {}

      Returns Promise<
          {
              created_at: string;
              created_by: string;
              evaluation_content: string;
              evaluation_id: number;
              id: number;
              name: string;
              patient_casefile_id: string;
              patient_process_id: number;
              status: string;
              updated_at: string;
              updated_by: string;
          }[],
      >

    • Fetch patient group therapy session records

      Uses Kipu Episodes API (v4) to retrieve group session attendance and notes

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              ancillary: boolean;
              billable: boolean;
              billable_claim_format: string;
              billing_codes: {
                  CCode?: string[];
                  Custom?: string[];
                  HCode?: string[];
                  RCode?: string[];
              };
              episode_first_name: string;
              episode_last_name: string;
              episode_note: string;
              episode_present: boolean;
              episode_session_end_time: string;
              episode_session_start_time: string;
              group_leader_full_name: string;
              group_leader_id: number;
              group_session_notes: string;
              group_session_title: string;
              group_session_topic: string;
              gs_group_session_id: string;
              id: number;
              location_id: number;
              pending_signers: { user_id: number; user_name: string }[];
              place_of_service: string;
              requires_review_signature: boolean;
              selected_billing_code: {
                  CCode?: string;
                  Custom?: string;
                  HCode?: string;
                  RCode?: string;
              };
              session_end_time: string;
              session_start_time: string;
              session_type: { id: number; name: string };
              signatures: {
                  created_at: string;
                  updated_at: string;
                  user_id: number;
                  user_name: string;
              }[];
              status: string;
          }[],
      >

      Array of group session records with attendance and signatures

    • Fetch patient medication orders and prescriptions

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              canceled: boolean;
              canceled_timestamp: string;
              created_at: string;
              diagnosis_code: string;
              discontinue_physician_id: number;
              discontinue_reason: string;
              discontinued: boolean;
              discontinued_timestamp: string;
              discontinued_user_id: number;
              discontinued_user_name: string;
              dispense_amount: string;
              dosage_form: string;
              erx: boolean;
              fdb_data: {
                  id: number;
                  medication_id: number;
                  ndc: string;
                  rxcui: string;
              }[];
              id: number;
              instructed_by: string;
              instructed_via: string;
              interaction_check_error: string;
              is_erx: boolean;
              is_prn: boolean;
              justification: string;
              mar_end_time: string;
              mar_start_time: string;
              medical_necessity_note: string;
              medication: string;
              name: string;
              no_substitutions: boolean;
              note: string;
              nurse_reviewed_at: string;
              nurse_reviewed_by: string;
              ordered_by: string;
              original_patient_order_id: number;
              patient_id: number;
              prn: boolean;
              refills: number;
              route: string;
              schedule_prn: boolean;
              status: string;
              updated_at: string;
              user_id: number;
              user_name: string;
              warnings: string;
          }[],
      >

      Array of medication orders with dosage, route, and scheduling information

    • Parameters

      • outcomeId: number

      Returns Promise<
          {
              annotations?: {
                  created_at: string;
                  id: number;
                  revised: boolean;
                  updated_at: string;
              }[];
              code: string;
              completed_at: string;
              created_at: string;
              description: string;
              episode_id: number;
              frequency_type: string;
              frequency_unit: string;
              frequency_value: string;
              id: number;
              issues?: {
                  code: string;
                  color: string;
                  computed_value: number;
                  created_at: string;
                  description: string;
                  detected: boolean;
                  episode_id: number;
                  function: string;
                  id: number;
                  issue_type: string;
                  levels: {
                      code: string;
                      detected: boolean;
                      id: number;
                      issue_id: number;
                      name: string;
                      operator_arguments: string;
                      operator_name: string;
                      order: number;
                      original_level_id: number;
                  }[];
                  name: string;
                  order: number;
                  read: boolean;
                  reviewed: boolean;
                  target_id: number;
                  target_type: string;
                  updated_at: string;
              }[];
              name: string;
              original_assessment_id: number;
              program_description: string;
              program_id: number;
              program_name: string;
              programmed_assessment_id: number;
              questions: {
                  answer_points: number
                  | null;
                  answer_value: number | null;
                  code: string;
                  completed_answers: {
                      id: number;
                      order: number;
                      points: number;
                      question_id: number;
                      text: string;
                      value: string;
                  }[];
                  created_at: string;
                  domains: {
                      created_at: string;
                      id: number;
                      name: string;
                      updated_at: string;
                  }[];
                  id: number;
                  max_value: number;
                  min_value: number;
                  order: number;
                  original_question_id: number;
                  possible_answers: {
                      code: string;
                      created_at: string;
                      default: boolean;
                      id: number;
                      order: number;
                      points: number;
                      question_id: number;
                      text: string;
                      updated_at: string;
                  }[];
                  question_type: string;
                  required: boolean;
                  text: string;
                  updated_at: string;
              }[];
              reference_code: string;
              reviewed: boolean;
              scheduled_assessment_id: number;
              status: string;
              status_changes: {
                  changed_by: {
                      user_first_name: string;
                      user_id: number;
                      user_last_name: string;
                      user_middle_name?: string
                      | null;
                      user_title: string;
                  };
                  created_at: string;
                  id: number;
                  message?: string
                  | null;
                  status: string;
                  updated_at: string;
              }[];
              title: string;
              updated_at: string;
          },
      >

    • Parameters

      • casefileId: string

      Returns Promise<
          {
              code: string;
              completed_at: string;
              created_at: string;
              description: string;
              episode_id: number;
              frequency_type: string;
              frequency_unit: string;
              frequency_value: string;
              id: number;
              name: string;
              original_assessment_id: number;
              program_description: string;
              program_id: number;
              program_name: string;
              programmed_assessment_id: number;
              reference_code: string;
              reviewed: boolean;
              scheduled_assessment_id: number;
              status: string;
              title: string;
              updated_at: string;
          }[],
      >

    • Fetch patient utilization review records

      Includes level of care assessments and authorization data

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              patient: {
                  casefile_id: string;
                  dob: string;
                  first_name: string;
                  last_name: string;
                  middle_name: string;
                  utilization_reviews: {
                      authorization_date: string;
                      authorization_number: string;
                      comment: string;
                      end_date: string
                      | null;
                      frequency: string | null;
                      id: number;
                      insurance: string;
                      lcd: boolean;
                      level_of_care: string | null;
                      next_care_level: string | null;
                      next_care_level_date: string | null;
                      next_review: string | null;
                      number_of_days: number | null;
                      start_date: string | null;
                      status: string;
                  }[];
              };
          },
      >

      Utilization review data with all assessment records

    • Fetch patient vital signs (temperature, pulse, blood pressure, etc.)

      Parameters

      • casefileId: string

        Patient identifier in format "patientId:patientMasterId"

      Returns Promise<
          {
              blood_pressure_diastolic: number;
              blood_pressure_systolic: number;
              id: number;
              interval_timestamp: string;
              o2_saturation: number;
              patient_id: number;
              pulse: number;
              respirations: number;
              temperature: number;
              user_name: string;
          }[],
      >

      Array of vital sign measurements

    • Parameters

      • casefileId: string

      Returns Promise<
          {
              logged_at: string
              | null;
              logged_by: string | null;
              program: string | null;
              start_date: string | null;
          }[],
      >

    • Fetch all patient programs (v4) — the catalog of programs configured for the account.

      Returns Promise<{ patient_program_id: number; patient_program_name: string }[]>

    • Fetch list of all users in the system

      Returns Promise<
          {
              email: string;
              first_name: string;
              home_phone: string;
              id: string;
              last_name: string;
              middle_name: string;
              mobile: string;
              title: string;
          }[],
      >

      Array of user records with credentials and roles