Candid Health subpackage_charge-capture.subpackage_charge-capture/v1 API

openapi: 3.1.0
info:
  title: API Reference subpackage_auth.subpackage_auth/default subpackage_charge-capture.subpackage_charge-capture/v1 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_charge-capture.subpackage_charge-capture/v1
paths:
  /api/charge_captures/v1:
    post:
      operationId: create
      summary: Create a Charge Capture
      tags:
      - subpackage_charge-capture.subpackage_charge-capture/v1
      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_charge-capture/v1:ChargeCapture'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - UnauthorizedError
                  content:
                    $ref: '#/components/schemas/type_commons:UnauthorizedErrorMessage'
                required:
                - errorName
                - content
        '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:
                    - ChargeExternalIdConflictError
                  content:
                    $ref: '#/components/schemas/type_charge-capture/v1:ChargeExternalIdConflictErrorMessage'
                required:
                - errorName
                - content
        '422':
          description: Error response with status 422
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - UnprocessableEntityError
                  content:
                    $ref: '#/components/schemas/type_commons:UnprocessableEntityErrorMessage'
                required:
                - errorName
                - content
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/type_charge-capture/v1:ChargeCaptureData'
                  description: Charge Capture data contains all the fields needed to create an encounter, but listed as optional. Candid will use this data when attempting to bundle multiple Charge Captures into a single encounter.
                charge_external_id:
                  type: string
                  description: A client-specified unique ID to associate with this encounter; for example, your internal encounter ID or a Dr. Chrono encounter ID. This field should not contain PHI.
                originating_system:
                  type: string
                  description: An optional string field denoting the originating system of the charge.
                claim_creation_category:
                  type: string
                  description: An optional string field denoting the user defined category of the claim creation.
                ehr_source_url:
                  type: string
                  description: External URL reference that links to Charge Capture details within the external system (e.g. the EHR visit page). Send full URL format for the external link (e.g. https://emr_charge_capture_url.com/123).
                patient_external_id:
                  type: string
                  description: The patient ID from the external EMR platform for the patient
                status:
                  $ref: '#/components/schemas/type_charge-capture/v1:ChargeCaptureStatus'
                  description: the status of the charge capture
                attachment_external_document_ids:
                  type: array
                  items:
                    type: string
                  description: Provide external attachment IDs which have been uploaded to Candid. They will be associated with the Encounter at Encounter creation time.
                metadata:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_custom-schemas/v1:SchemaInstance'
                  description: 'Key-value pairs that adhere to metadata schemas.

                    Multiple metadata instances can be associated with a charge capture.'
                hl7_message_type:
                  $ref: '#/components/schemas/type_charge-capture/v1:Hl7MessageType'
                  description: The HL7 message type that produced this write. Used to differentiate post-submission update behavior. Sent by HL7 producers (conduit); null for manual / script writes.
              required:
              - data
              - charge_external_id
              - patient_external_id
              - status
    get:
      operationId: get-all
      summary: Get all Charge Captures
      tags:
      - subpackage_charge-capture.subpackage_charge-capture/v1
      parameters:
      - name: limit
        in: query
        description: Maximum number of entities per page, defaults to 100.
        required: false
        schema:
          type: integer
      - name: sort
        in: query
        description: Defaults to created_at
        required: false
        schema:
          $ref: '#/components/schemas/type_charge-capture/v1:ChargeCaptureSortField'
      - name: sort_direction
        in: query
        description: Sort direction. Defaults to descending order if not provided.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortDirection'
      - name: page_token
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:PageToken'
      - name: patient_external_id
        in: query
        description: The patient ID from the external EMR platform for the patient
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: the status of the charge captures
        required: false
        schema:
          $ref: '#/components/schemas/type_charge-capture/v1:ChargeCaptureStatus'
      - name: charge_external_id
        in: query
        description: 'A client-specified unique ID to associate with this encounter;

          for example, your internal encounter ID or a Dr. Chrono encounter ID.

          This field should not contain PHI.'
        required: false
        schema:
          type: string
      - name: date_of_service_min
        in: query
        description: 'Date formatted as YYYY-MM-DD; eg: 2019-08-24.

          This date must be the local date in the timezone where the service occurred.'
        required: false
        schema:
          type: string
          format: date
      - name: date_of_service_max
        in: query
        description: 'Date formatted as YYYY-MM-DD; eg: 2019-08-24.

          This date must be the local date in the timezone where the service occurred.'
        required: false
        schema:
          type: string
          format: date
      - name: claim_ids
        in: query
        description: A list of claim IDs to filter by. This will return all charge captures that have a resulting claim with one of the IDs in this list.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:EncounterId'
      - name: claim_creation_ids
        in: query
        description: A list of Claim Creation IDs to filter by.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:ChargeCaptureClaimCreationId'
      - name: billing_provider_npis
        in: query
        description: A list of billing provider NPIs to filter by. This will return all charge captures with one of the NPIs in this list.
        required: false
        schema:
          type: string
      - name: service_facility_name
        in: query
        description: A string to filter by. This will return all charge captures with this service facility name.
        required: false
        schema:
          type: string
      - name: primary_payer_ids
        in: query
        description: A list of primary payer IDs to filter by. This will return all charge captures with one of the primary payer IDs in this list.
        required: false
        schema:
          type: string
      - name: rendering_provider_npis
        in: query
        description: A list of rendering provider NPIs to filter by. This will return all charge captures with one of the NPIs in this list.
        required: false
        schema:
          type: string
      - name: rendering_provider_names
        in: query
        description: A list of rendering provider names to filter by. This will return all charge captures with one of the names in this list.
        required: false
        schema:
          type: string
      - name: supervising_provider_npis
        in: query
        description: A list of supervising provider NPIs to filter by. This will return all charge captures with one of the NPIs in this list.
        required: false
        schema:
          type: string
      - name: supervising_provider_names
        in: query
        description: A list of supervising provider names to filter by. This will return all charge captures with one of the names in this list.
        required: false
        schema:
          type: string
      - name: claim_creation_category
        in: query
        description: A list of claim creation categories to filter by. This will return all charge capture claim_creations which include one or more charges with one of the names in this list.
        required: false
        schema:
          type: string
      - name: tags
        in: query
        description: A list of tags to filter by. This will return all charge captures with one of the tags.
        required: false
        schema:
          type: string
      - name: primary_payer_names
        in: query
        description: A list of primary payer names to filter by. This will return all charge captures with one of the names.
        required: false
        schema:
          type: string
      - name: patient_names
        in: query
        description: A list of patient names to filter by. This will return all charge captures with one of the names.
        required: false
        schema:
          type: string
      - name: exclude_charges_linked_to_claims
        in: query
        description: Whether to exclude charge captures which are part of a claim creation.
        required: false
        schema:
          type: boolean
      - name: patient_external_id_ranked_sort
        in: query
        description: The patient ID from the external EMR platform for the patient
        required: false
        schema:
          type: string
      - name: status_ranked_sort
        in: query
        description: The charge capture status to show first
        required: false
        schema:
          $ref: '#/components/schemas/type_charge-capture/v1:ChargeCaptureStatus'
      - name: charge_external_id_ranked_sort
        in: query
        description: 'A client-specified unique ID to associate with this encounter;

          for example, your internal encounter ID or a Dr. Chrono encounter ID.

          This field should not contain PHI.'
        required: false
        schema:
          type: string
      - name: date_of_service_min_ranked_sort
        in: query
        description: 'Date formatted as YYYY-MM-DD; eg: 2019-08-24.

          This date must be the local date in the timezone where the service occurred.'
        required: false
        schema:
          type: string
          format: date
      - name: date_of_service_max_ranked_sort
        in: query
        description: 'Date formatted as YYYY-MM-DD; eg: 2019-08-24.

          This date must be the local date in the timezone where the service occurred.'
        required: false
        schema:
          type: string
          format: date
      - name: search_term
        in: query
        description: 'Filter by any of the following fields: charge_id, claim_id, patient external_id,

          patient date of birth, patient first name, patient last name,

          or charge external id.'
        required: false
        schema:
          type: string
      - name: billable_status
        in: query
        description: Defines if the Encounter is to be billed by Candid to the responsible_party. Examples for when this should be set to NOT_BILLABLE include if the Encounter has not occurred yet or if there is no intention of ever billing the responsible_party.
        required: false
        schema:
          $ref: '#/components/schemas/type_encounters/v4:BillableStatusType'
      - name: responsible_party
        in: query
        description: Defines the party to be billed with the initial balance owed on the claim. Use SELF_PAY if you intend to bill self pay/cash pay.
        required: false
        schema:
          $ref: '#/components/schemas/type_encounters/v4:ResponsiblePartyType'
      - name: claim_ids_ranked_sort
        in: query
        description: A list of claim IDs to show first. This will return all charge captures that have a resulting claim with one of the IDs in this list.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:EncounterId'
      - name: claim_creation_ids_ranked_sort
        in: query
        description: A list of Claim Creation IDs to show first.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:ChargeCaptureClaimCreationId'
      - name: billing_provider_npis_ranked_sort
        in: query
        description: A list of billing provider NPIs to show first. This will return all charge captures with one of the NPIs in this list.
        required: false
        schema:
          type: string
      - name: service_facility_name_ranked_sort
        in: query
        description: A string to show first. This will return all charge captures with this service facility name.
        required: false
        schema:
          type: string
      - name: primary_payer_ids_ranked_sort
        in: query
        description: A list of primary payer IDs to show first. This will return all charge captures with one of the primary payer IDs in this list.
        required: false
        schema:
          type: string
      - name: rendering_provider_npis_ranked_sort
        in: query
        description: A list of rendering provider NPIs to show first. This will return all charge captures with one of the NPIs in this list.
        required: false
        schema:
          type: string
      - name: rendering_provider_names_ranked_sort
        in: query
        description: A list of rendering provider names to show first. This will return all charge captures with one of the names in this list.
        required: false
        schema:
          type: string
      - name: supervising_provider_npis_ranked_sort
        in: query
        description: A list of supervising provider NPIs to show first. This will return all charge captures with one of the NPIs in this list.
        required: false
        schema:
          type: string
      - name: supervising_provider_names_ranked_sort
        in: query
        description: A list of supervising provider names to show first. This will return all charge captures with one of the names in this list.
        required: false
        schema:
          type: string
      - name: claim_status
        in: query
        description: the status of the claim to filter by created from charge capture bundle.
        required: false
        schema:
          $ref: '#/components/schemas/type_claims:ClaimStatus'
      - name: claim_creation_category_ranked_sort
        in: query
        description: A list of claim creation categories to sort by. This will return all charge capture claim_creations which include one or more charges with one of the names in this list.
        required: false
        schema:
          type: string
      - name: tags_ranked_sort
        in: query
        description: A list of tags. This will return all charge captures with one of the tags.
        required: false
        schema:
          type: string
      - name: primary_payer_names_ranked_sort
        in: query
        description: A list of primary payer names to sort by. This will return all charge captures with one of the names.
        required: false
        schema:
          type: string
      - name: patient_names_ranked_sort
        in: query
        description: A list of patient names to sort by. This will return all charge captures with one of the names.
        required: false
        schema:
          type: string
      - 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_charge-capture/v1:ChargeCapturePage'
  /api/charge_captures/v1/create-from-pre-encounter:
    post:
      operationId: create-from-pre-encounter-patient
      summary: Create a Charge Capture from pre-encounter patient and appointment
      description: "Create a Charge Capture from a pre-encounter patient and appointment. This endpoint is intended to be used by consumers who are managing\npatients and appointments in the pre-encounter service and is currently under development. Consumers who are not taking advantage\nof the pre-encounter service should use the standard create endpoint.\n\nAt encounter creation time, information from the provided patient and appointment objects will be populated\nwhere applicable. In particular, the following fields are populated from the patient and appointment objects:\n  - Patient\n  - Referring Provider\n  - Subscriber Primary\n  - Subscriber Secondary\n  - Referral Number\n  - Responsible Party\n  - Guarantor\n\nNote that these fields should not be populated in the ChargeCaptureData property of this endpoint, as they will be overwritten at encounter creation time.\n\nUtilizing this endpoint opts you into automatic updating of the encounter when the patient or appointment is updated, assuming the\nencounter has not already been submitted or adjudicated."
      tags:
      - subpackage_charge-capture.subpackage_charge-capture/v1
      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_charge-capture/v1:ChargeCapture'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - UnauthorizedError
                  content:
                    $ref: '#/components/schemas/type_commons:UnauthorizedErrorMessage'
                required:
                - errorName
                - content
        '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:
                    - ChargeExternalIdConflictError
                  content:
                    $ref: '#/components/schemas/type_charge-capture/v1:ChargeExternalIdConflictErrorMessage'
                required:
                - errorName
                - content
        '422':
          description: Error response with status 422
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - UnprocessableEntityError
                  content:
                    $ref: '#/components/schemas/type_commons:UnprocessableEntityErrorMessage'
                required:
                - errorName
                - content
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/type_charge-capture/v1:ChargeCaptureData'
                  description: Charge Capture data contains all the fields needed to create an encounter, but listed as optional. Candid will use this data when attempting to bundle multiple Charge Captures into a single encounter.
                charge_external_id:
                  type: string
                  description: A client-specified unique ID to associate with this encounter; for example, your internal encounter ID or a Dr. Chrono encounter ID. This field should not contain PHI.
                pre_encounter_patient_id:
                  $ref: '#/components/schemas/type_commons:PreEncounterPatientId'
                pre_encounter_appointment_ids:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_commons:PreEncounterAppointmentId'
                originating_system:
                  type: string
                  description: An optional string field denoting the originating system of the charge.
                claim_creation_category:
                  type: string
                  description: An optional string field denoting the user defined category of the claim creation.
                ehr_source_url:
                  type: string
                  description: External URL reference that links to Charge Capture details within the external system (e.g. the EHR visit page). Send full URL format for the external link (e.g. https://emr_charge_capture_url.com/123).
                status:
                  $ref: '#/components/schemas/type_charge-capture/v1:ChargeCaptureStatus'
                  description: the status of the charge capture
                attachment_external_document_ids:
                  type: array
                  items:
                    type: string
                  description: Provide external attachment IDs which have been uploaded to Candid. They will be associated with the Encounter at Encounter creation time.
                hl7_message_type:
                  $ref: '#/components/schemas/type_charge-capture/v1:Hl7MessageType'
                  description: The HL7 message type that produced this write. Used to differentiate post-submission update behavior. Sent by HL7 producers (conduit); null for manual / script writes.
              required:
              - data
              - charge_external_id
              - pre_encounter_patient_id
              - pre_encounter_appointment_ids
              - status
  /api/charge_captures/v1/changes:
    patch:
      operationId: update-post-billed-changes
      summary: Update a ChargeCapturePostBilledChange
      tags:
      - subpackage_charge-capture.subpackage_charge-capture/v1
      parameters:
      - name: Authorization
        in: header
        description: OAuth authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: This list of updates will always return at most 1 update that is not resolved. The singular update will contain the difference between the updated charge and the created encounter.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/type_charge-capture/v1:ChargeCapturePostBilledChange'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - UnauthorizedError
                  content:
                    $ref: '#/components/schemas/type_commons:UnauthorizedErrorMessage'
                required:
                - errorName
                - content
        '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:
              type: object
              properties:
                charge_capture_change_ids:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_commons:ChargeCapturePostBilledChangeId'
                  description: 'A list of UUIDs corresponding to ChargeCapturePostBilledChanges.

                    All of the charges sent will be marked as resolved'
                resolved:
                  type: boolean
                  description: 'Whether the change has been resolved. If true, the change will be marked as resolved.

                    If false, the change will be marked as unresolved.'
              required:
              - charge_capture_change_ids
              - resolved
  /api/charge_captures/v1/{charge_capture_id}:
    patch:
      operationId: update
      summary: Update Charge Capture
      tags:
      - subpackage_charge-capture.subpackage_charge-capture/v1
      parameters:
      - name: charge_capture_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:ChargeCaptureId'
      - 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_charge-capture/v1:ChargeCapture'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorName:
                    type: string
                    enum:
                    - UnauthorizedError
                  content:
                    $ref: '#/components/schemas/type_commons:UnauthorizedErrorMessage'
                required:
                - errorName
                - content
        '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:
                    - UnprocessableEntityError
                  content:
                    $ref: '#/components/schemas/type_commons:UnprocessableEntityErrorMessage'
                required:
                - errorName
                - content
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/type_charge-capture/v1:ChargeCaptureData'
                charge_external_id:
                  type: string
                  description: 'A client-specified unique ID to associate with this encounter;

                    for example, your internal encounter ID or a Dr. Chrono encounter ID.

                    This field should not contain PHI.'
                ehr_source_url:
                  type: string
                  description: 'External URL reference that links to Charge Capture details within the external system (e.g. the EHR visit page).

                    Send full URL format for the external link (e.g. https://emr_charge_capture_url.com/123).'
                originating_system:
                  type: string
                  description: An optional string field denoting the originating system of the charge.
                claim_creation_category:
                  type: string
                  description: An optional string field denoting the user defined category of the claim creation.
                patient_external_id:
                  type: string
                  description: The patient ID from the external EMR platform for the patient
                status:
                  $ref: '#/components/schemas/type_charge-capture/v1:ChargeCaptureStatus'
                  description: the status of the charge capture
                attachment_external_document_ids:
                  type: array
                  items:
                    type: string
                  description: Provide external attachment IDs which have been uploaded to Candid. They will be associated with the Encounter at Encounter creation time.
                metadata:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_custom-schemas/v1:SchemaInstance'
                  description: 'Key-value pairs that adhere to metadata schemas.

                    Multiple metadata instances can be associated with a charge capture.'
                hl7_message_typ

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/candid-health/refs/heads/main/openapi/candid-health-subpackage-charge-capture-subpackage-charge-capture-v1-api-openapi.yml