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_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. get: operationId: get summary: Get 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' /api/charge_captures/v1/find-by-metadata: post: operationId: find-by-metadata summary: Find Charge Captures by Metadata 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:ChargeCapturePage' requestBody: content: application/json: schema: type: object properties: metadata: type: array items: $ref: '#/components/schemas/type_custom-schemas/v1:SchemaInstance' description: 'Filter by metadata schema instances. This will return all charge captures that match any of the provided schema instances.' limit: type: integer description: Maximum number of entities per page, defaults to 100. page_token: $ref: '#/components/schemas/type_commons:PageToken' required: - metadata components: schemas: type_commons:ChargeCapturePostBilledChangeId: type: string format: uuid title: ChargeCapturePostBilledChangeId type_commons:EntityNotFoundErrorMessage: type: object properties: id: type: string required: - id title: EntityNotFoundErrorMessage type_commons:PreEncounterPatientId: type: string format: uuid title: PreEncounterPatientId type_commons:PageToken: type: string title: PageToken type_commons:PreEncounterAppointmentId: type: string format: uuid title: PreEncounterAppointmentId type_commons:ChargeCaptureId: type: string format: uuid title: ChargeCaptureId type_commons:UnprocessableEntityErrorMessage: type: object properties: message: type: string title: UnprocessableEntityErrorMessage type_claims:ClaimStatus: type: string enum: - biller_received - coded - submitted_to_payer - missing_information - not_billable - waiting_for_provider - era_received - rejected - denied - paid - paid_incorrectly - finalized_paid - finalized_denied - held_by_customer - era_requires_review title: ClaimStatus type_commons:SortDirection: type: string enum: - asc - desc title: SortDirection type_commons:UnauthorizedErrorMessage: type: object properties: message: type: string title: UnauthorizedErrorMessage type_commons:EncounterId: type: string format: uuid title: EncounterId type_commons:ChargeCaptureClaimCreationId: type: string format: uuid title: ChargeCaptureClaimCreationId securitySchemes: OAuthScheme: type: http scheme: bearer description: OAuth 2.0 authentication