openapi: 3.1.0 info: title: API Reference subpackage_auth.subpackage_auth/default subpackage_encounters.subpackage_encounters/v4 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_encounters.subpackage_encounters/v4 paths: /api/encounters/v4: get: operationId: get-all summary: Get all encounters tags: - subpackage_encounters.subpackage_encounters/v4 parameters: - name: limit in: query description: Maximum number of entities per page, defaults to 100. required: false schema: type: integer - name: claim_status in: query description: Indicates the current status of an insurance claim within the billing process. required: false schema: $ref: '#/components/schemas/type_claims:ClaimStatus' - name: sort in: query description: Defaults to created_at:desc. required: false schema: $ref: '#/components/schemas/type_encounters/v4:EncounterSortOptions' - name: page_token in: query required: false schema: $ref: '#/components/schemas/type_commons:PageToken' - name: date_of_service_min in: query description: 'Date formatted as YYYY-MM-DD; eg: 2019-08-25.' required: false schema: type: string format: date - name: date_of_service_max in: query description: 'Date formatted as YYYY-MM-DD; eg: 2019-08-25.' required: false schema: type: string format: date - name: primary_payer_names in: query description: Comma delimited string. required: false schema: type: string - name: search_term in: query description: 'Filter by any of the following fields: encounter_id, claim_id, patient external_id, patient date of birth, patient first name, patient last name, or encounter external id.' required: false schema: type: string - name: external_id in: query description: Filter to an exact match on encounter external_id, if one exists. required: false schema: $ref: '#/components/schemas/type_commons:EncounterExternalId' - name: diagnoses_updated_since in: query description: 'ISO 8601 timestamp; ideally in UTC (although not required): 2019-08-24T14:15:22Z.' required: false schema: type: string format: date-time - name: tag_ids in: query description: Filter by name of tags on encounters. required: false schema: $ref: '#/components/schemas/type_tags:TagId' - name: work_queue_id in: query required: false schema: $ref: '#/components/schemas/type_commons:WorkQueueId' - 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: owner_of_next_action in: query description: The party who is responsible for taking the next action on an Encounter, as defined by ownership of open Tasks. required: false schema: $ref: '#/components/schemas/type_encounters/v4:EncounterOwnerOfNextActionType' - name: patient_external_id in: query description: The patient ID from the external EMR platform for the patient required: false schema: type: string - name: include_merged_patient_data in: query description: If true and patient_external_id is set, then also include the encounters of all alternative patients. required: false schema: type: boolean - 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_encounters/v4:EncounterPage' '422': description: Error response with status 422 content: application/json: schema: type: object properties: errorName: type: string enum: - HttpRequestValidationsError content: type: array items: $ref: '#/components/schemas/type_commons:RequestValidationError' required: - errorName - content '500': description: Error response with status 500 content: application/json: schema: type: object properties: errorName: type: string enum: - InternalError content: $ref: '#/components/schemas/type_commons:InternalErrorMessage' required: - errorName - content post: operationId: create summary: Create professional encounter tags: - subpackage_encounters.subpackage_encounters/v4 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_encounters/v4:Encounter' '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: Raised for universal claims that fail to provider either an attending_provider or rendering_provider value content: application/json: schema: type: object properties: errorName: type: string enum: - EncounterRenderingOrAttendingProviderRequired description: Raised for universal claims that fail to provider either an attending_provider or rendering_provider value content: $ref: '#/components/schemas/type_encounters/v4:EncounterRenderingOrAttendingProviderRequiredError' description: Raised for universal claims that fail to provider either an attending_provider or rendering_provider value required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_encounters/v4:EncounterCreate' /api/encounters/v4/{encounter_id}: get: operationId: get summary: Get encounter tags: - subpackage_encounters.subpackage_encounters/v4 parameters: - name: encounter_id in: path required: true schema: $ref: '#/components/schemas/type_commons:EncounterId' - 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_encounters/v4:Encounter' patch: operationId: update summary: Update professional encounter tags: - subpackage_encounters.subpackage_encounters/v4 parameters: - name: encounter_id in: path required: true schema: $ref: '#/components/schemas/type_commons:EncounterId' - 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_encounters/v4:Encounter' '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: - PayerPlanGroupPayerDoesNotMatchInsuranceCardHttpError content: $ref: '#/components/schemas/type_encounters/v4:PayerPlanGroupPayerDoesNotMatchInsuranceCardError' required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_encounters/v4:EncounterUpdate' /api/encounters/v4/universal: post: operationId: create-universal summary: Create institutional or professional encounter description: 'Notice: The UB-04 Data File, 2025, is copyrighted by American Hospital Association (AHA), Chicago, Illinois. No portion of the THE UB-04 Data File, may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior express, written consent of AHA.' tags: - subpackage_encounters.subpackage_encounters/v4 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_encounters/v4:Encounter' '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: Raised for universal claims that fail to provider either an attending_provider or rendering_provider value content: application/json: schema: type: object properties: errorName: type: string enum: - EncounterRenderingOrAttendingProviderRequired description: Raised for universal claims that fail to provider either an attending_provider or rendering_provider value content: $ref: '#/components/schemas/type_encounters/v4:EncounterRenderingOrAttendingProviderRequiredError' description: Raised for universal claims that fail to provider either an attending_provider or rendering_provider value required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_encounters-universal:UniversalEncounterCreate' /api/encounters/v4/create-from-pre-encounter/universal: post: operationId: create-from-pre-encounter-patient-universal summary: Create institutional or professional encounter from pre-encounter patient and appointment description: "Create an encounter 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\nThe endpoint will create an encounter from the provided fields, pulling information from the provided patient and appointment objects\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\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.\n\nNotice: The UB-04 Data File, 2025, is copyrighted by American Hospital Association (AHA), Chicago, Illinois.\nNo portion of the THE UB-04 Data File, may be reproduced, stored in a retrieval system, or transmitted,\nin any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior\nexpress, written consent of AHA." tags: - subpackage_encounters.subpackage_encounters/v4 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_encounters/v4:Encounter' '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: - PayerPlanGroupPayerDoesNotMatchInsuranceCardHttpError content: $ref: '#/components/schemas/type_encounters/v4:PayerPlanGroupPayerDoesNotMatchInsuranceCardError' required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_encounters-universal:UniversalEncounterCreateFromPreEncounter' /api/encounters/v4/create-from-pre-encounter: post: operationId: create-from-pre-encounter-patient summary: Create professional encounter from pre-encounter patient and appointment description: "Create an encounter 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\nThe endpoint will create an encounter from the provided fields, pulling information from the provided patient and appointment objects\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\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_encounters.subpackage_encounters/v4 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_encounters/v4:Encounter' '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: - PayerPlanGroupPayerDoesNotMatchInsuranceCardHttpError content: $ref: '#/components/schemas/type_encounters/v4:PayerPlanGroupPayerDoesNotMatchInsuranceCardError' required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_encounters/v4:EncounterCreateFromPreEncounter' /api/encounters/v4/{encounter_id}/universal: patch: operationId: update-universal summary: Update institutional or professional encounter description: 'Notice: The UB-04 Data File, 2025, is copyrighted by American Hospital Association (AHA), Chicago, Illinois. No portion of the THE UB-04 Data File, may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior express, written consent of AHA.' tags: - subpackage_encounters.subpackage_encounters/v4 parameters: - name: encounter_id in: path required: true schema: $ref: '#/components/schemas/type_commons:EncounterId' - 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_encounters/v4:Encounter' '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: - PayerPlanGroupPayerDoesNotMatchInsuranceCardHttpError content: $ref: '#/components/schemas/type_encounters/v4:PayerPlanGroupPayerDoesNotMatchInsuranceCardError' required: - errorName - content requestBody: content: application/json: schema: $ref: '#/components/schemas/type_encounters-universal:UniversalEncounterUpdate' components: schemas: type_commons:State: type: string enum: - AA - AE - AP - AL - AK - AS - AZ - AR - CA - CO - CT - DC - DE - FL - FM - GA - GU - HI - ID - IL - IN - IA - KS - KY - LA - ME - MD - MA - MH - MI - MN - MP - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - OH - OK - OR - PA - PR - PW - RI - SC - SD - TN - TX - UT - VI - VT - VA - WA - WV - WI - WY title: State type_commons:EntityNotFoundErrorMessage: type: object properties: id: type: string required: - id title: EntityNotFoundErrorMessage type_commons:StreetAddressShortZip: type: object properties: address1: type: string address2: type: string city: type: string state: $ref: '#/components/schemas/type_commons:State' zip_code: type: string description: 5-digit zip code zip_plus_four_code: type: string description: 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4 required: - address1 - city - state - zip_code title: StreetAddressShortZip type_commons:DelayReasonCode: type: string enum: - '1' - '2' - '3' - '4' - '5' - '6' - '7' - '8' - '9' - '10' - '11' - '15' - '16' - '17' description: Code indicating the reason why a request was delayed title: DelayReasonCode type_commons:EncounterExternalId: type: string title: EncounterExternalId type_commons:UnauthorizedErrorMessage: type: object properties: message: type: string title: UnauthorizedErrorMessage type_commons:FacilityTypeCode: type: string enum: - '01' - '02' - '03' - '04' - '05' - '06' - '07' - 08 - 09 - '10' - '11' - '12' - '13' - '14' - '15' - '16' - '17' - '18' - '19' - '20' - '21' - '22' - '23' - '24' - '25' - '26' - '31' - '32' - '33' - '34' - '41' - '42' - '49' - '50' - '51' - '52' - '53' - '54' - '55' - '56' - '57' - '58' - '60' - '61' - '62' - '65' - '71' - '72' - '81' - '99' description: 'Box 24B on the CMS-1500 claim form. Line-level place of service is not currently supported. 02 for telemedicine, 11 for in-person. Full list here: https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set' title: FacilityTypeCode type_individual:SubscriberCreate: type: object properties: first_name: type: string last_name: type: string gender: $ref: '#/components/schemas/type_individual:Gender' patient_relationship_to_subscriber_code: $ref: '#/components/schemas/type_commons:PatientRelationshipToInsuredCodeAll' date_of_birth: type: string format: date address: $ref: '#/components/schemas/type_commons:StreetAddressShortZip' insurance_card: $ref: '#/components/schemas/type_insurance-cards/v2:InsuranceCardCreate' description: Please reference our [Payer Information](https://docs.joincandidhealth.com/introduction/payer-information) documentation for more details on how to populate the `insurance_card` fields. required: - first_name - last_name - gender - patient_relationship_to_subscriber_code - insurance_card title: SubscriberCreate type_encounters-universal:UniversalEncounterUpdate: type: object properties: benefits_assigned_to_provider: type: boolean description: Whether this patient has authorized insurance payments to be made to you, not them. If false, patient may receive reimbursement. Box 13 on the CMS-1500 claim form or Form Locator 53 on a UB-04 claim form. prior_authorization_number: $ref: '#/components/schemas/type_encounters/v4:PriorAuthorizationNumber' description: Box 23 on the CMS-1500 claim form or Form Locator 63 on a UB-04 claim form. external_id: $ref: '#/components/schemas/type_commons:EncounterExternalId' 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.' date_of_service: type: string format: date 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. Box 24a on the CMS-1500 claim form or Form Locator 45 on the UB-04 claim form. If service occurred over a range of dates, this should be the start date. If service lines have distinct date_of_service values, updating the encounter''s date_of_service will fail. If all service line date_of_service values are the same, updating the encounter''s date_of_service will update all service line date_of_service values.' tag_ids: type: array items: $ref: '#/components/schemas/type_tags:TagId' description: Names of tags that should be on the encounter. Note all tags on encounter will be overridden with this list. billable_status: $ref: '#/components/schemas/type_encounters/v4:BillableStatusType' 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. responsible_party: $ref: '#/components/schemas/type_encounters/v4:ResponsiblePartyType' 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. provider_accepts_assignment: type: boolean description: Whether you have accepted the patient's authorization for insurance payments to be made to you, not them. Box 27 on the CMS-1500 claim form. There is no exact equivalent of this field on a UB-04 claim, however contributes to the concept of Form Locator 53. synchronicity: $ref: '#/components/schemas/type_encounters/v4:SynchronicityType' description: Whether or not this was a synchronous or asynchronous encounter. Asynchronous encounters occur when providers and patients communicate online using forms, instant messaging, or other pre-recorded digital mediums. Synchronous encounters occur in live, real-time settings where the patient interacts directly with the provider, such as over video or a phone call. place_of_service_code: $ref: '#/components/schemas/type_commons:FacilityTypeCode' description: Box 24B on the CMS-1500 claim form. 837p Loop2300, CLM-05-1. 02 for telemedicine, 11 for in-person. Full list [here](https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set). appointment_type: type: string description: 'Human-readable description of the appointment type (ex: "Acupuncture - Headaches").' end_date_of_service: type: string format: date description: 'Date formatted as YYYY-MM-DD; eg: 2019-08-25. This date must be the local date in the timezone where the service occurred. If omitted, the Encounter is assumed to be for a single day. Must not be temporally before the date_of_service field. If service lines have distinct end_date_of_service values, updating the encounter''s end_date_of_service will fail. If all service line end_date_of_service values are the same, updating the encounter''s end_date_of_service will update all service line date_of_service values.' additional_information: type: string description: 'Defines additional information on the claim needed by the payer. Box 19 on the CMS-1500 claim form or Form Locator 80 on a UB-04 claim form.' service_authorization_exception_code: $ref: '#/components/schemas/type_encounters/v4:ServiceAuthorizationExceptionCode' description: '837p Loop2300 REF*4N Required when mandated by government law or regulation to obtain authorization for specific service(s) but, for the reasons listed in one of the enum values of ServiceAuthorizationExceptionCode, the service was performed without obtaining the authorization.' admission_date: type: string format: date description: '837p Loop2300 DTP*435, CMS-1500 Box 18 or UB-04 Form Locator 12. Required on all ambulance claims when the patient was known to be admitted to the hospital. OR Required on all claims involving inpatient medical visits.' discharge_date: type: string format: date description: 837p Loop2300 DTP*096, CMS-1500 Box 18 Required for inpatient claims when the patient was discharged from the facility and the discharge date is known. Not used on an institutional claim. onset_of_current_illness_or_symptom_date: type: string format: date description: "837p Loop2300 DTP*431, CMS-1500 Box 14\nRequired for the initial medical service or visit performed in response to a medical emergency when the date is available and is different than the date of service.\nOR\nThis date is the onset of acute symptoms for the current illness or condition.\n For UB-04 claims, this is populated separately via occurrence codes." last_menstrual_period_date: type: string format: date description: '837p Loop2300 DTP*484, CMS-1500 Box 14 Required when, in the judgment of the provider, the services on this claim are related to the patient''s pregnancy.de This field is populated separately via occurrence codes for UB-04 claim forms.' delay_reason_code: $ref: '#/components/schemas/type_commons:DelayReasonCode' description: 'Code indicating the reason why a claim submission was delayed. Corresponds to CLM-20 in the 837 specification (both professional and institutional).' patient_authorized_release: type: boolean description: 'Whether this patient has authorized the release of medical information for billing purpose. Box 12 on the CMS-1500 claim form or Form Locator 52 on a UB-04 claim form.' referral_number: type: string description: Refers to REF*9F on the 837p. Value cannot be greater than 50 characters. secondary_payer_carrier_code: type: string description: When Medicaid is billed as the secondary payer the Carrier Code is used to identify the primary payer. This is required for certain states. epsdt_referral: $ref: '#/components/schemas/type_encounters/v4:EPSDTReferral' description: Refers to Box 24H on the CMS1500 form and Loop 2300 CRC - EPSDT Referral on the 837P and 837i form clinical_notes: type: array items: $ref: '#/components/schemas/type_encounters/v4:ClinicalNoteCategoryCreate' description: Holds a collection of clinical observations made by healthcare providers during patient encounters. Please note that medical records for appeals should be sent using the Encounter Attachments API. claim_supplemental_information: type: array items: $ref: '#/components/schemas/type_encounters/v4:ClaimSupplementalInformation' description: Refers to Loop 2300 - Segment PWK on the 837P and 837i form. No more than 10 entries are permitted. schema_instances: type: array items: $ref: '#/components/schemas/type_custom-schemas/v1:SchemaInstance' description: 'Key-value pairs that must adhere to a schema created via the Custom Schema API. Multiple schema instances cannot be created for the same schema on an encounter. Updating schema instances utilizes PUT semantics, so the schema instances on the encounter will be set to whatever inputs are provided. If null is provided as an input, then the encounter''s schema instances will be cleared.' existing_medications: type: array items: $ref: '#/components/schemas/type_encounters/v4:Medication' description: 'Existing medications that should be on the encounter. Note all current existing medications on encounter will be overridden with this list.' guarantor: $ref: '#/components/schemas/type_guarantor/v1:GuarantorUpdate' description: Personal and contact info for the guarantor of the patient responsibility. subscriber_primary: $ref: '#/components/schemas/type_individual:SubscriberCreate' description: Contains details of the primary insurance subscriber. subscriber_secondary: $ref: '#/components/schemas/type_individual:SubscriberCreate' description: Contains details of the secondary insurance subscriber. subscriber_tertiary: $ref: '#/components/schemas/type_individual:SubscriberCreate' description: Contains details of the tertiary insurance subscriber. pay_to_address: $ref: '#/components/schemas/type_commons:StreetAddressLongZip' description: Specifies the address to which payments for the claim should be sent. initial_referring_provider: $ref: '#/components/schemas/type_encounter-providers/v2:InitialReferringProviderUpdate' description: 'The second iteration of Loop ID-2310 on an 837P form. Use code "P3 - Primary Care Provider" in this loop to indicate the initial referral from the primary care provider or whatever provider wrote the initial referral for this patient''s episode of care being billed/reported in this transaction. Not used in an 837i claim' referring_provider: $ref: '#/components/schemas/type_encounter-providers/v2:ReferringProviderUpdate' description: 'The final provider who referred the services that were rendered. All physicians who order services or refer Medicare beneficiaries must report this data.' patient: $ref: '#/components/schemas/type_individual:PatientUpdate' description: Contains the identification information of the individual receiving medical services. rendering_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProviderUpdate' description: 'The rendering provider is the practitioner -- physician, nurse practitioner, etc. -- performing the service. For telehealth services, the rendering provider performs the visit, asynchronous communication, or other service. The rendering provider address should generally be the same as the service facility address.' service_facility: $ref: '#/components/schemas/type_service-facility:EncounterServiceFacilityUpdate' description: Encounter Service facility is typically the location a medical service was rendered, such as a provider office or hospital. For telehealth, service facility can represent the provider's location when the service was delivered (e.g., home), or the location where an in-person visit would have taken place, whichever is easier to identify. If the provider is in-network, service facility may be defined in payer contracts. Box 32 on the CMS-1500 claim form. There is no equivalent on the paper UB-04 claim form, but this field is equivalent to Loop 2310E Service Facility Location details on an 837i form, and is used when this is different to the entity identified as the Billing Provider. Note that for an in-network claim to be successfully adjudicated, the service facility address listed supervising_provider: $ref: '#/components/schemas/type_encounter-providers/v2:SupervisingProviderUpdate' description: Required when the rendering provider is supervised by a physician. If not required by this implementation guide, do not send. treating_provider: $ref: '#/components/schemas/type_encounter-providers/v2:TreatingProviderUpdate' description: The treating provider is the provider who treats the patient. This is supported for professional and institutional encounters. billing_provider: $ref: '#/components/schemas/type_encounter-providers/v2:BillingProviderUpdate' description: The billing provider is the provider or business entity submitting the claim. Billing provider may be, but is not necessarily, the same person/NPI as the rendering provider. From a payer's perspective, this represents the person or entity being reimbursed. When a contract exists with the target payer, the billing provider should be the entity contracted with the payer. In some circumstances, this will be an individual provider. In that case, submit that provider's NPI and the tax ID (TIN) that the provider gave to the payer during contracting. In other cases, the billing entity will be a medical group. If so, submit the group NPI and the group's tax ID. Box 33 on the CMS-1500 claim or Form Locator 1 on a UB-04 claim form. place_of_service_code_as_submitted: $ref: '#/components/schemas/type_commons:FacilityTypeCode' description: Box 24B on the CMS-1500 claim form. 837p Loop2300, CLM-05-1. This box is not used on a UB-04 or 837i claim form. 02 for telemedicine, 11 for in-person. Full list [here](https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set). related_causes_information: $ref: '#/components/schemas/type_related-causes/v1:RelatedCausesInformationUpdate' description: Corresponds to box 10a on the CMS-1500 (Loop 2300 on 837) property_casualty_claim_number: type: string description: 837p Loop2010 REF02, CMS1500 Box 11b accident_date: type: string format: date description: 837p Loop2300 DTP*439, CMS1500 Box 15 property_casualty_patient_identifier: $ref: '#/components/schemas/type_property-and-casualty/v1:PropertyCasualtyPatientIdentifierUpdate' description: 'Patient identifier for Property and Casualty claims 837p Loop 2010CA' health_care_code_information: $ref: '#/components/schemas/type_health-care-code-information/v1:HealthCareCodeInformationUpdate' description: The health care code information associated with this encounter, which includes things such as diagnoses, vitals, procedures, occurrences, reason for visit, and numerous other code related fields. attending_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProviderUpdate' description: 837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has overall responsibility for the patient in institutional claims processing. admission_hour: type: integer description: '837i Loop 2300 DTP-03 Extension of the admission date with hour (0-23 integer) details.' admission_type_code: $ref: '#/components/schemas/type_x12/v1:TypeOfAdmissionOrVisitCode' description: 837i Loop 2300 CL1-01 Code used to indicate the priority of an admission or visit. Equivalent to Form Locator 14 Priority of Admission on a UB-04 claim, not used on CMS-1500 claim forms. admission_source_code: $ref: '#/components/schemas/type_x12/v1:PointOfOriginForAdmissionOrVisitCode' description: 837i Loop 2300 CLI1-02 Code used to indicate the conditions under which an admission occurs. Equivalent to Form Locator 15 Point of Origin on a UB-04 claim, not used on CMS-1500 claim forms. discharge_hour: type: integer description: '837i Loop 2300 DTP-03 Extension of the discharge date with hour (0-23 integer) details.' discharge_status: $ref: '#/components/schemas/type_x12/v1:PatientDischargeStatusCode' description: '837i CL1-03 or Form Locator 17 on a UB-04 claim form. This is a required field on UB-04 claims. Code indicating patient status as of the "statement covers through date".' operating_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProviderUpdate' description: 837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has primary responsibility for surgical procedures in institutional claims processing. other_operating_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProviderUpdate' description: 837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has secondary responsibility for surgical procedures in institutional claims processing. Only used when operating_provider is also set. type_of_bill: $ref: '#/components/schemas/type_x12/v1:TypeOfBillCompositeUpdate' description: Four digit code used in institutional forms to indicate the type of bill (e.g., hospital inpatient, hospital outpatient). First digit is a leading 0, followed by the type_of_facility, type_of_care, then frequency_code. Professional forms are not required to submit this attribute. You may send the 4 digit code via raw_code, or each individual digit separately via composite_codes. accident_state_or_province_code: $ref: '#/components/schemas/type_commons:State' description: 837i-REF1000 -- an optional state indicating where an accident related to the encounter occurred. submission_expectation: $ref: '#/components/schemas/type_encounters/v4:EncounterSubmissionExpectation' description: Describes the currently expected target form for this encounter. This effects what validations and queues the form is processed under. When this value is not set, it should be assumed to be TARGET_PROFESSIONAL. title: UniversalEncounterUpdate type_service-facility:EncounterServiceFacilityBase: type: object properties: organization_name: type: string npi: type: string description: 'An NPI specific to the service facility if applicable, i.e. if it has one and is not under the billing provider''s NPI. Box 32 section (a) of the CMS-1500 claim form.' address: $ref: '#/components/schemas/type_commons:StreetAddressLongZip' description: zip_plus_four_code is required for service facility address. When the zip_plus_four_code is not available use "9998" as per CMS documentation. secondary_identification: type: string description: 'An additional identifier for the service facility other than the facility''s NPI. Some payers may require this field. Potential examples: state license number, provider commercial number, or location number. Box 32 section (b) of the CMS-1500 claim form.' mammography_certification_number: type: string description: The associated mammography certification number for this service facility. This is a 6 digit code assigned by the FDA. required: - organization_name - address description: 'Encounter Service facility is typically the location a medical service was rendered, such as a provider office or hospital. For telehealth, service facility can represent the provider''s location when the service was delivered (e.g., home), or the location where an in-person visit would have taken place, whichever is easier to identify. If the provider is in-network, service facility may be defined in payer contracts. Box 32 on the CMS-1500 claim form. Note that for an in-network claim to be successfully adjudicated, the service facility address listed on claims must match what was provided to the payer during the credentialing process.' title: EncounterServiceFacilityBase type_commons:EncounterId: type: string format: uuid title: EncounterId type_tags:TagId: type: string title: TagId 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:PhoneNumber: type: object properties: number: type: string type: $ref: '#/components/schemas/type_commons:PhoneNumberType' required: - number - type title: PhoneNumber type_commons:WorkQueueId: type: string title: WorkQueueId type_commons:PhoneNumberType: type: string enum: - Home - Mobile - Work title: PhoneNumberType type_commons:PreEncounterPatientId: type: string format: uuid title: PreEncounterPatientId type_commons:StreetAddressLongZip: type: object properties: address1: type: string address2: type: string city: type: string state: $ref: '#/components/schemas/type_commons:State' zip_code: type: string description: 5-digit zip code zip_plus_four_code: type: string description: 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4 required: - address1 - city - state - zip_code - zip_plus_four_code title: StreetAddressLongZip type_individual:PatientUpdate: type: object properties: first_name: type: string last_name: type: string gender: $ref: '#/components/schemas/type_individual:Gender' external_id: type: string description: The ID used to identify this individual in your system. For example, your internal patient ID or an EHR patient ID. date_of_birth: type: string format: date description: Box 3 on the CMS-1500 claim form or Form Locator 10 on a UB-04 claim form. The date format should be in ISO 8601 date; formatted YYYY-MM-DD (i.e. 2012-02-01) address: $ref: '#/components/schemas/type_commons:StreetAddressShortZip' description: Box 5 on the CMS-1500 claim form or Form Locator 9 on a UB-04 claim form. phone_numbers: type: array items: $ref: '#/components/schemas/type_commons:PhoneNumber' phone_consent: type: boolean email: $ref: '#/components/schemas/type_commons:Email' email_consent: type: boolean auto_charge_consent: type: boolean non_insurance_payers: type: array items: $ref: '#/components/schemas/type_non-insurance-payers/v1:NonInsurancePayerId' description: On update, we will replace the existing list of non-insurance payers with the new list if populated. non_insurance_payers_info: type: array items: $ref: '#/components/schemas/type_individual:PatientNonInsurancePayerInfoCreate' description: On update, we will replace the existing list of non-insurance payers with the new list if populated. title: PatientUpdate type_commons:PreEncounterAppointmentId: type: string format: uuid title: PreEncounterAppointmentId type_commons:PatientRelationshipToInsuredCodeAll: type: string enum: - '01' - '04' - '05' - '07' - '10' - '15' - '17' - '18' - '19' - '20' - '21' - '22' - '23' - '24' - '29' - '32' - '33' - '36' - '39' - '40' - '41' - '43' - '53' - G8 title: PatientRelationshipToInsuredCodeAll type_commons:PageToken: type: string title: PageToken type_individual:PatientClinicalTrialInfoCreate: type: object properties: clinical_trial_arm: type: string clinical_trial_id: $ref: '#/components/schemas/type_commons:ClinicalTrialId' required: - clinical_trial_id title: PatientClinicalTrialInfoCreate type_commons:Email: type: string title: Email type_commons:InternalErrorMessage: type: object properties: message: type: string title: InternalErrorMessage type_individual:PatientNonInsurancePayerInfoCreate: type: object properties: non_insurance_payer_id: $ref: '#/components/schemas/type_non-insurance-payers/v1:NonInsurancePayerId' member_id: type: string clinical_trial_info: type: array items: $ref: '#/components/schemas/type_individual:PatientClinicalTrialInfoCreate' required: - non_insurance_payer_id title: PatientNonInsurancePayerInfoCreate type_commons:ClinicalTrialId: type: string format: uuid title: ClinicalTrialId type_encounters-universal:UniversalEncounterCreateFromPreEncounter: type: object properties: external_id: $ref: '#/components/schemas/type_commons:EncounterExternalId' 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.' date_of_service: type: string format: date 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. Box 24a on the CMS-1500 claim form or Form Locator 45 on the UB-04 claim form. If service occurred over a range of dates, this should be the start date. date_of_service must be defined on either the encounter or the service lines but not both. If there are greater than zero service lines, it is recommended to specify date_of_service on the service_line instead of on the encounter to prepare for future API versions.' end_date_of_service: type: string format: date description: 'Date formatted as YYYY-MM-DD; eg: 2019-08-25. This date must be the local date in the timezone where the service occurred. If omitted, the Encounter is assumed to be for a single day. Must not be temporally before the date_of_service field. If there are greater than zero service lines, it is recommended to specify end_date_of_service on the service_line instead of on the encounter to prepare for future API versions.' patient_authorized_release: type: boolean description: 'Whether this patient has authorized the release of medical information for billing purpose. Box 12 on the CMS-1500 claim form or Form Locator 52 on a UB-04 claim form.' benefits_assigned_to_provider: type: boolean description: 'Whether this patient has authorized insurance payments to be made to you, not them. If false, patient may receive reimbursement. Box 13 on the CMS-1500 claim form or Form Locator 53 on a UB-04 claim form.' provider_accepts_assignment: type: boolean description: 'Whether you have accepted the patient''s authorization for insurance payments to be made to you, not them. Box 27 on the CMS-1500 claim form. There is no exact equivalent of this field on a UB-04 claim, however contributes to the concept of Form Locator 53.' appointment_type: type: string description: 'Human-readable description of the appointment type (ex: "Acupuncture - Headaches").' existing_medications: type: array items: $ref: '#/components/schemas/type_encounters/v4:Medication' interventions: type: array items: $ref: '#/components/schemas/type_encounters/v4:Intervention' pay_to_address: $ref: '#/components/schemas/type_commons:StreetAddressLongZip' description: Specifies the address to which payments for the claim should be sent. synchronicity: $ref: '#/components/schemas/type_encounters/v4:SynchronicityType' description: 'Whether or not this was a synchronous or asynchronous encounter. Asynchronous encounters occur when providers and patients communicate online using forms, instant messaging, or other pre-recorded digital mediums. Synchronous encounters occur in live, real-time settings where the patient interacts directly with the provider, such as over video or a phone call.' vitals: $ref: '#/components/schemas/type_encounters/v4:Vitals' billable_status: $ref: '#/components/schemas/type_encounters/v4:BillableStatusType' 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.' additional_information: type: string description: 'Defines additional information on the claim needed by the payer. Box 19 on the CMS-1500 claim form or Form Locator 80 on a UB-04 claim form.' service_authorization_exception_code: $ref: '#/components/schemas/type_encounters/v4:ServiceAuthorizationExceptionCode' description: '837p Loop2300 REF*4N Required when mandated by government law or regulation to obtain authorization for specific service(s) but, for the reasons listed in one of the enum values of ServiceAuthorizationExceptionCode, the service was performed without obtaining the authorization.' admission_date: type: string format: date description: '837p Loop2300 DTP*435, CMS-1500 Box 18 or UB-04 Form Locator 12. Required on all ambulance claims when the patient was known to be admitted to the hospital. OR Required on all claims involving inpatient medical visits.' discharge_date: type: string format: date description: 837p Loop2300 DTP*096, CMS-1500 Box 18 Required for inpatient claims when the patient was discharged from the facility and the discharge date is known. Not used on an institutional claim. onset_of_current_illness_or_symptom_date: type: string format: date description: "837p Loop2300 DTP*431, CMS-1500 Box 14\nRequired for the initial medical service or visit performed in response to a medical emergency when the date is available and is different than the date of service.\nOR\nThis date is the onset of acute symptoms for the current illness or condition.\n For UB-04 claims, this is populated separately via occurrence codes." last_menstrual_period_date: type: string format: date description: '837p Loop2300 DTP*484, CMS-1500 Box 14 Required when, in the judgment of the provider, the services on this claim are related to the patient''s pregnancy. This field is populated separately via occurrence codes for UB-04 claim forms.' delay_reason_code: $ref: '#/components/schemas/type_commons:DelayReasonCode' description: 'Code indicating the reason why a claim submission was delayed. Corresponds to CLM-20 in the 837 specification (both professional and institutional).' pre_encounter_patient_id: $ref: '#/components/schemas/type_commons:PreEncounterPatientId' pre_encounter_appointment_ids: type: array items: $ref: '#/components/schemas/type_commons:PreEncounterAppointmentId' billing_provider: $ref: '#/components/schemas/type_encounter-providers/v2:BillingProvider' description: The billing provider is the provider or business entity submitting the claim. Billing provider may be, but is not necessarily, the same person/NPI as the rendering provider. From a payer's perspective, this represents the person or entity being reimbursed. When a contract exists with the target payer, the billing provider should be the entity contracted with the payer. In some circumstances, this will be an individual provider. In that case, submit that provider's NPI and the tax ID (TIN) that the provider gave to the payer during contracting. In other cases, the billing entity will be a medical group. If so, submit the group NPI and the group's tax ID. Box 33 on the CMS-1500 claim or Form Locator 1 on a UB-04 claim form. initial_referring_provider: $ref: '#/components/schemas/type_encounter-providers/v2:InitialReferringProvider' description: 'The second iteration of Loop ID-2310 on an 837P form. Use code "P3 - Primary Care Provider" in this loop to indicate the initial referral from the primary care provider or whatever provider wrote the initial referral for this patient''s episode of care being billed/reported in this transaction. Not used in an 837i claim' supervising_provider: $ref: '#/components/schemas/type_encounter-providers/v2:SupervisingProvider' description: Required when the rendering provider is supervised by a physician. If not required by this implementation guide, do not send. service_facility: $ref: '#/components/schemas/type_service-facility:EncounterServiceFacilityBase' description: Encounter Service facility is typically the location a medical service was rendered, such as a provider office or hospital. For telehealth, service facility can represent the provider's location when the service was delivered (e.g., home), or the location where an in-person visit would have taken place, whichever is easier to identify. If the provider is in-network, service facility may be defined in payer contracts. Box 32 on the CMS-1500 claim form. There is no equivalent on the paper UB-04 claim form, but this field is equivalent to Loop 2310E Service Facility Location details on an 837i form, and is used when this is different to the entity identified as the Billing Provider. Note that for an in-network claim to be successfully adjudicated, the service facility address listed. This field is mutually exclusive with service_facility_id — providing both will result in a 422 error. service_facility_id: $ref: '#/components/schemas/type_organization-service-facilities/v2:OrganizationServiceFacilityId' description: The ID of an existing Organization Service Facility to use for this encounter. The service facility's canonical data (name, address, NPI, etc.) will be populated automatically. If the value does not match an existing Organization Service Facility, the request will fail with a 422 error. This field is mutually exclusive with service_facility — providing both will result in a 422 error. clinical_notes: type: array items: $ref: '#/components/schemas/type_encounters/v4:ClinicalNoteCategoryCreate' description: Holds a collection of clinical observations made by healthcare providers during patient encounters. Please note that medical records for appeals should be sent using the Encounter Attachments API. billing_notes: type: array items: $ref: '#/components/schemas/type_billing-notes/v2:BillingNoteBase' description: 'Spot to store misc, human-readable, notes about this encounter to be used in the billing process.' patient_histories: type: array items: $ref: '#/components/schemas/type_encounters/v4:PatientHistoryCategory' external_claim_submission: $ref: '#/components/schemas/type_claim-submission/v1:ExternalClaimSubmissionCreate' description: 'To be included for claims that have been submitted outside of Candid. Candid supports posting remits and payments to these claims and working them in-platform (e.g. editing, resubmitting).' tag_ids: type: array items: $ref: '#/components/schemas/type_tags:TagId' description: Names of tags that should be on the encounter. schema_instances: type: array items: $ref: '#/components/schemas/type_custom-schemas/v1:SchemaInstance' description: 'Key-value pairs that must adhere to a schema created via the Custom Schema API. Multiple schema instances cannot be created for the same schema on an encounter.' related_causes_information: $ref: '#/components/schemas/type_related-causes/v1:RelatedCausesInformationCreate' description: Corresponds to box 10a on the CMS-1500 (Loop 2300 on 837) property_casualty_claim_number: type: string description: 837p Loop2010 REF02, CMS1500 Box 11b accident_date: type: string format: date description: 837p Loop2300 DTP*439, CMS1500 Box 15 property_casualty_patient_identifier: $ref: '#/components/schemas/type_property-and-casualty/v1:PropertyCasualtyPatientIdentifierCreate' description: 'Patient identifier for Property and Casualty claims 837p Loop 2010CA' submission_expectation: $ref: '#/components/schemas/type_encounters/v4:EncounterSubmissionExpectation' description: Describes the currently expected target form for this encounter. This effects what validations and queues the form is processed under. rendering_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProvider' description: 'The rendering provider is the practitioner -- physician, nurse practitioner, etc. -- performing the service. For telehealth services, the rendering provider performs the visit, asynchronous communication, or other service. The rendering provider address should generally be the same as the service facility address.' health_care_code_information: $ref: '#/components/schemas/type_health-care-code-information/v1:HealthCareCodeInformationCreate' description: The health care code information associated with this encounter, which includes things such as diagnoses, vitals, procedures, occurrences, reason for visit, and numerous other code related fields. place_of_service_code: $ref: '#/components/schemas/type_commons:FacilityTypeCode' description: Box 24B on the CMS-1500 claim form. 837p Loop2300, CLM-05-1. This box is not used on a UB-04 or 837i claim form. 02 for telemedicine, 11 for in-person. Full list [here](https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set). service_lines: type: array items: $ref: '#/components/schemas/type_service-lines/v2:UniversalServiceLineCreate' attending_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProvider' description: 837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has overall responsibility for the patient in institutional claims processing. admission_hour: type: integer description: '837i Loop 2300 DTP-03 Extension of the admission date with hour (0-23 integer) details.' admission_type_code: $ref: '#/components/schemas/type_x12/v1:TypeOfAdmissionOrVisitCode' description: 837i Loop 2300 CL1-01 Code used to indicate the priority of an admission or visit. Equivalent to Form Locator 14 Priority of Admission on a UB-04 claim, not used on CMS-1500 claim forms. admission_source_code: $ref: '#/components/schemas/type_x12/v1:PointOfOriginForAdmissionOrVisitCode' description: 837i Loop 2300 CLI1-02 Code used to indicate the conditions under which an admission occurs. Equivalent to Form Locator 15 Point of Origin on a UB-04 claim, not used on CMS-1500 claim forms. discharge_hour: type: integer description: '837i Loop 2300 DTP-03 Extension of the discharge date with hour (0-23 integer) details.' discharge_status: $ref: '#/components/schemas/type_x12/v1:PatientDischargeStatusCode' description: '837i CL1-03 or Form Locator 17 on a UB-04 claim form. This is a required field on UB-04 claims. Code indicating patient status as of the "statement covers through date" .' operating_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProvider' description: 837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has primary responsibility for surgical procedures in institutional claims processing. other_operating_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProvider' description: 837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has secondary responsibility for surgical procedures in institutional claims processing. Only used when operating_provider is also set. type_of_bill: $ref: '#/components/schemas/type_x12/v1:TypeOfBillCompositeUpdate' description: Four digit code used in institutional forms to indicate the type of bill (e.g., hospital inpatient, hospital outpatient). First digit is a leading 0, followed by the type_of_facility, type_of_care, then frequency_code. Professional forms are not required to submit this attribute. You may send the 4 digit code via raw_code, or each individual digit separately via composite_codes. accident_state_or_province_code: $ref: '#/components/schemas/type_commons:State' description: 837i-REF1000 -- an optional state indicating where an accident related to the encounter occurred. required: - external_id - patient_authorized_release - benefits_assigned_to_provider - provider_accepts_assignment - billable_status - pre_encounter_patient_id - pre_encounter_appointment_ids - billing_provider - submission_expectation title: UniversalEncounterCreateFromPreEncounter type_service-facility:EncounterServiceFacilityUpdate: type: object properties: organization_name: type: string npi: type: string description: 'An NPI specific to the service facility if applicable, i.e. if it has one and is not under the billing provider''s NPI. Box 32 section (a) of the CMS-1500 claim form.' address: $ref: '#/components/schemas/type_commons:StreetAddressLongZip' description: zip_plus_four_code is required for service facility address. When the zip_plus_four_code is not available use "9998" as per CMS documentation. secondary_identification: type: string description: 'An additional identifier for the service facility other than the facility''s NPI. Some payers may require this field. Potential examples: state license number, provider commercial number, or location number. Box 32 section (b) of the CMS-1500 claim form.' mammography_certification_number: type: string description: The associated mammography certification number for this service facility. This is a 6 digit code assigned by the FDA. title: EncounterServiceFacilityUpdate type_commons:RequestValidationError: type: object properties: fieldName: type: string humanReadableMessage: type: string required: - fieldName title: RequestValidationError type_encounters-universal:UniversalEncounterCreate: type: object properties: external_id: $ref: '#/components/schemas/type_commons:EncounterExternalId' 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.' date_of_service: type: string format: date 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. Box 24a on the CMS-1500 claim form or Form Locator 45 on the UB-04 claim form. If service occurred over a range of dates, this should be the start date. date_of_service must be defined on either the encounter or the service lines but not both. If there are greater than zero service lines, it is recommended to specify date_of_service on the service_line instead of on the encounter to prepare for future API versions.' end_date_of_service: type: string format: date description: 'Date formatted as YYYY-MM-DD; eg: 2019-08-25. This date must be the local date in the timezone where the service occurred. If omitted, the Encounter is assumed to be for a single day. Must not be temporally before the date_of_service field. If there are greater than zero service lines, it is recommended to specify end_date_of_service on the service_line instead of on the encounter to prepare for future API versions.' patient_authorized_release: type: boolean description: 'Whether this patient has authorized the release of medical information for billing purpose. Box 12 on the CMS-1500 claim form or Form Locator 52 on a UB-04 claim form.' benefits_assigned_to_provider: type: boolean description: 'Whether this patient has authorized insurance payments to be made to you, not them. If false, patient may receive reimbursement. Box 13 on the CMS-1500 claim form or Form Locator 53 on a UB-04 claim form.' provider_accepts_assignment: type: boolean description: 'Whether you have accepted the patient''s authorization for insurance payments to be made to you, not them. Box 27 on the CMS-1500 claim form. There is no exact equivalent of this field on a UB-04 claim, however contributes to the concept of Form Locator 53.' appointment_type: type: string description: 'Human-readable description of the appointment type (ex: "Acupuncture - Headaches").' existing_medications: type: array items: $ref: '#/components/schemas/type_encounters/v4:Medication' interventions: type: array items: $ref: '#/components/schemas/type_encounters/v4:Intervention' pay_to_address: $ref: '#/components/schemas/type_commons:StreetAddressLongZip' description: Specifies the address to which payments for the claim should be sent. synchronicity: $ref: '#/components/schemas/type_encounters/v4:SynchronicityType' description: 'Whether or not this was a synchronous or asynchronous encounter. Asynchronous encounters occur when providers and patients communicate online using forms, instant messaging, or other pre-recorded digital mediums. Synchronous encounters occur in live, real-time settings where the patient interacts directly with the provider, such as over video or a phone call.' vitals: $ref: '#/components/schemas/type_encounters/v4:Vitals' billable_status: $ref: '#/components/schemas/type_encounters/v4:BillableStatusType' 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.' additional_information: type: string description: 'Defines additional information on the claim needed by the payer. Box 19 on the CMS-1500 claim form or Form Locator 80 on a UB-04 claim form.' service_authorization_exception_code: $ref: '#/components/schemas/type_encounters/v4:ServiceAuthorizationExceptionCode' description: '837p Loop2300 REF*4N Required when mandated by government law or regulation to obtain authorization for specific service(s) but, for the reasons listed in one of the enum values of ServiceAuthorizationExceptionCode, the service was performed without obtaining the authorization.' admission_date: type: string format: date description: '837p Loop2300 DTP*435, CMS-1500 Box 18 or UB-04 Form Locator 12. Required on all ambulance claims when the patient was known to be admitted to the hospital. OR Required on all claims involving inpatient medical visits.' discharge_date: type: string format: date description: 837p Loop2300 DTP*096, CMS-1500 Box 18 Required for inpatient claims when the patient was discharged from the facility and the discharge date is known. Not used on an institutional claim. onset_of_current_illness_or_symptom_date: type: string format: date description: "837p Loop2300 DTP*431, CMS-1500 Box 14\nRequired for the initial medical service or visit performed in response to a medical emergency when the date is available and is different than the date of service.\nOR\nThis date is the onset of acute symptoms for the current illness or condition.\n For UB-04 claims, this is populated separately via occurrence codes." last_menstrual_period_date: type: string format: date description: '837p Loop2300 DTP*484, CMS-1500 Box 14 Required when, in the judgment of the provider, the services on this claim are related to the patient''s pregnancy. This field is populated separately via occurrence codes for UB-04 claim forms.' delay_reason_code: $ref: '#/components/schemas/type_commons:DelayReasonCode' description: 'Code indicating the reason why a claim submission was delayed. Corresponds to CLM-20 in the 837 specification (both professional and institutional).' patient: $ref: '#/components/schemas/type_individual:PatientCreate' description: Contains the identification information of the individual receiving medical services. referring_provider: $ref: '#/components/schemas/type_encounter-providers/v2:ReferringProvider' description: 'The final provider who referred the services that were rendered. All physicians who order services or refer Medicare beneficiaries must report this data.' initial_referring_provider: $ref: '#/components/schemas/type_encounter-providers/v2:InitialReferringProvider' description: 'The second iteration of Loop ID-2310 on an 837P form. Use code "P3 - Primary Care Provider" in this loop to indicate the initial referral from the primary care provider or whatever provider wrote the initial referral for this patient''s episode of care being billed/reported in this transaction. Not used in an 837i claim' supervising_provider: $ref: '#/components/schemas/type_encounter-providers/v2:SupervisingProvider' description: Required when the rendering provider is supervised by a physician. If not required by this implementation guide, do not send. treating_provider: $ref: '#/components/schemas/type_encounter-providers/v2:TreatingProvider' description: The treating provider is the provider who treats the patient. This is only supported for professional encounters. service_facility: $ref: '#/components/schemas/type_service-facility:EncounterServiceFacilityBase' description: Encounter Service facility is typically the location a medical service was rendered, such as a provider office or hospital. For telehealth, service facility can represent the provider's location when the service was delivered (e.g., home), or the location where an in-person visit would have taken place, whichever is easier to identify. If the provider is in-network, service facility may be defined in payer contracts. Box 32 on the CMS-1500 claim form. There is no equivalent on the paper UB-04 claim form, but this field is equivalent to Loop 2310E Service Facility Location details on an 837i form, and is used when this is different to the entity identified as the Billing Provider. Note that for an in-network claim to be successfully adjudicated, the service facility address listed. This field is mutually exclusive with service_facility_id — providing both will result in a 422 error. service_facility_id: $ref: '#/components/schemas/type_organization-service-facilities/v2:OrganizationServiceFacilityId' description: The ID of an existing Organization Service Facility to use for this encounter. The service facility's canonical data (name, address, NPI, etc.) will be populated automatically. If the value does not match an existing Organization Service Facility, the request will fail with a 422 error. This field is mutually exclusive with service_facility — providing both will result in a 422 error. subscriber_primary: $ref: '#/components/schemas/type_individual:SubscriberCreate' description: 'Subscriber_primary is required when responsible_party is INSURANCE_PAY (i.e. when the claim should be billed to insurance). These are not required fields when responsible_party is SELF_PAY (i.e. when the claim should be billed to the patient). However, if you collect this for patients, even self-pay, we recommend including it when sending encounters to Candid. Note: Cash Pay is no longer a valid payer_id in v4, please use responsible party to define self-pay claims.' subscriber_secondary: $ref: '#/components/schemas/type_individual:SubscriberCreate' description: Please always include this when you have it, even for self-pay claims. subscriber_tertiary: $ref: '#/components/schemas/type_individual:SubscriberCreate' description: Please always include this when you have it, even for self-pay claims. prior_authorization_number: $ref: '#/components/schemas/type_encounters/v4:PriorAuthorizationNumber' description: Box 23 on the CMS-1500 claim form or Form Locator 63 on a UB-04 claim form. responsible_party: $ref: '#/components/schemas/type_encounters/v4:ResponsiblePartyType' description: Defines the party to be billed with the initial balance owed on the claim. clinical_notes: type: array items: $ref: '#/components/schemas/type_encounters/v4:ClinicalNoteCategoryCreate' description: Holds a collection of clinical observations made by healthcare providers during patient encounters. Please note that medical records for appeals should be sent using the Encounter Attachments API. billing_notes: type: array items: $ref: '#/components/schemas/type_billing-notes/v2:BillingNoteBase' description: 'Spot to store misc, human-readable, notes about this encounter to be used in the billing process.' patient_histories: type: array items: $ref: '#/components/schemas/type_encounters/v4:PatientHistoryCategory' guarantor: $ref: '#/components/schemas/type_guarantor/v1:GuarantorCreate' description: Personal and contact info for the guarantor of the patient responsibility. external_claim_submission: $ref: '#/components/schemas/type_claim-submission/v1:ExternalClaimSubmissionCreate' description: 'To be included for claims that have been submitted outside of Candid. Candid supports posting remits and payments to these claims and working them in-platform (e.g. editing, resubmitting).' tag_ids: type: array items: $ref: '#/components/schemas/type_tags:TagId' description: Names of tags that should be on the encounter. schema_instances: type: array items: $ref: '#/components/schemas/type_custom-schemas/v1:SchemaInstance' description: 'Key-value pairs that must adhere to a schema created via the Custom Schema API. Multiple schema instances cannot be created for the same schema on an encounter.' referral_number: type: string description: Refers to REF*9F on the 837p and 837i. Value cannot be greater than 50 characters. epsdt_referral: $ref: '#/components/schemas/type_encounters/v4:EPSDTReferral' description: Refers to Box 24H on the CMS1500 form and Loop 2300 CRC - EPSDT Referral on the 837P and 837i form claim_supplemental_information: type: array items: $ref: '#/components/schemas/type_encounters/v4:ClaimSupplementalInformation' description: Refers to Loop 2300 - Segment PWK on the 837P and 837i forms. No more than 10 entries are permitted. secondary_payer_carrier_code: type: string description: When Medicaid is billed as the secondary payer the Carrier Code is used to identify the primary payer. This is required for certain states. related_causes_information: $ref: '#/components/schemas/type_related-causes/v1:RelatedCausesInformationCreate' description: Corresponds to box 10a on the CMS-1500 (Loop 2300 on 837) property_casualty_claim_number: type: string description: 837p Loop2010 REF02, CMS1500 Box 11b accident_date: type: string format: date description: 837p Loop2300 DTP*439, CMS1500 Box 15 property_casualty_patient_identifier: $ref: '#/components/schemas/type_property-and-casualty/v1:PropertyCasualtyPatientIdentifierCreate' description: 'Patient identifier for Property and Casualty claims 837p Loop 2010CA' billing_provider: $ref: '#/components/schemas/type_encounter-providers/v2:BillingProvider' description: The billing provider is the provider or business entity submitting the claim. Billing provider may be, but is not necessarily, the same person/NPI as the rendering provider. From a payer's perspective, this represents the person or entity being reimbursed. When a contract exists with the target payer, the billing provider should be the entity contracted with the payer. In some circumstances, this will be an individual provider. In that case, submit that provider's NPI and the tax ID (TIN) that the provider gave to the payer during contracting. In other cases, the billing entity will be a medical group. If so, submit the group NPI and the group's tax ID. Box 33 on the CMS-1500 claim or Form Locator 1 on a UB-04 claim form. place_of_service_code: $ref: '#/components/schemas/type_commons:FacilityTypeCode' description: Box 24B on the CMS-1500 claim form. 837p Loop2300, CLM-05-1. This box is not used on a UB-04 or 837i claim form. 02 for telemedicine, 11 for in-person. Full list [here](https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set). rendering_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProvider' description: 'The rendering provider is the practitioner -- physician, nurse practitioner, etc. -- performing the service. For telehealth services, the rendering provider performs the visit, asynchronous communication, or other service. The rendering provider address should generally be the same as the service facility address.' service_lines: type: array items: $ref: '#/components/schemas/type_service-lines/v2:UniversalServiceLineCreate' health_care_code_information: $ref: '#/components/schemas/type_health-care-code-information/v1:HealthCareCodeInformationCreate' description: The health care code information associated with this encounter, which includes things such as diagnoses, vitals, procedures, occurrences, reason for visit, and numerous other code related fields. submission_expectation: $ref: '#/components/schemas/type_encounters/v4:EncounterSubmissionExpectation' description: Describes the currently expected target form for this encounter. This can change later, but it orients this encounter in the pipeline and effects reporting. attending_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProvider' description: 837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has overall responsibility for the patient in institutional claims processing. admission_hour: type: integer description: '837i Loop 2300 DTP-03 Extension of the admission date with hour (0-23 integer) details.' admission_type_code: $ref: '#/components/schemas/type_x12/v1:TypeOfAdmissionOrVisitCode' description: 837i Loop 2300 CL1-01 Code used to indicate the priority of an admission or visit. Equivalent to Form Locator 14 Priority of Admission on a UB-04 claim, not used on CMS-1500 claim forms. admission_source_code: $ref: '#/components/schemas/type_x12/v1:PointOfOriginForAdmissionOrVisitCode' description: 837i Loop 2300 CLI1-02 Code used to indicate the conditions under which an admission occurs. Equivalent to Form Locator 15 Point of Origin on a UB-04 claim, not used on CMS-1500 claim forms. discharge_hour: type: integer description: '837i Loop 2300 DTP-03 Extension of the discharge date with hour (0-23 integer) details.' discharge_status: $ref: '#/components/schemas/type_x12/v1:PatientDischargeStatusCode' description: '837i CL1-03 or Form Locator 17 on a UB-04 claim form. This is a required field on UB-04 claims. Code indicating patient status as of the "statement covers through date" .' operating_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProvider' description: 837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has primary responsibility for surgical procedures in institutional claims processing. other_operating_provider: $ref: '#/components/schemas/type_encounter-providers/v2:RenderingProvider' description: 837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has secondary responsibility for surgical procedures in institutional claims processing. Only used when operating_provider is also set. type_of_bill: $ref: '#/components/schemas/type_x12/v1:TypeOfBillCompositeUpdate' description: Four digit code used in institutional forms to indicate the type of bill (e.g., hospital inpatient, hospital outpatient). First digit is a leading 0, followed by the type_of_facility, type_of_care, then frequency_code. Professional forms are not required to submit this attribute. You may send the 4 digit code via raw_code, or each individual digit separately via composite_codes. accident_state_or_province_code: $ref: '#/components/schemas/type_commons:State' description: 837i-REF1000 -- an optional state indicating where an accident related to the encounter occurred. required: - external_id - patient_authorized_release - benefits_assigned_to_provider - provider_accepts_assignment - billable_status - patient - responsible_party - billing_provider - submission_expectation title: UniversalEncounterCreate type_individual:PatientCreate: type: object properties: first_name: type: string last_name: type: string gender: $ref: '#/components/schemas/type_individual:Gender' external_id: type: string description: The ID used to identify this individual in your system. For example, your internal patient ID or an EHR patient ID. date_of_birth: type: string format: date description: Box 3 on the CMS-1500 claim form or Form Locator 10 on a UB-04 claim form. The date format should be in ISO 8601 date; formatted YYYY-MM-DD (i.e. 2012-02-01) address: $ref: '#/components/schemas/type_commons:StreetAddressShortZip' description: Box 5 on the CMS-1500 claim form or Form Locator 9 on a UB-04 claim form. phone_numbers: type: array items: $ref: '#/components/schemas/type_commons:PhoneNumber' phone_consent: type: boolean description: Defaults to false email: $ref: '#/components/schemas/type_commons:Email' non_insurance_payers: type: array items: $ref: '#/components/schemas/type_non-insurance-payers/v1:NonInsurancePayerId' non_insurance_payers_info: type: array items: $ref: '#/components/schemas/type_individual:PatientNonInsurancePayerInfoCreate' email_consent: type: boolean description: Defaults to false auto_charge_consent: type: boolean description: Defaults to false required: - first_name - last_name - gender - external_id - date_of_birth - address title: PatientCreate type_individual:Gender: type: string enum: - male - female - other - not_given - unknown title: Gender securitySchemes: OAuthScheme: type: http scheme: bearer description: OAuth 2.0 authentication