API ReferenceEncountersV4

Create institutional or professional encounter from pre-encounter patient and appointment

Beta
Create an encounter from a pre-encounter patient and appointment. This endpoint is intended to be used by consumers who are managing patients and appointments in the pre-encounter service and is currently under development. Consumers who are not taking advantage of the pre-encounter service should use the standard create endpoint. The endpoint will create an encounter from the provided fields, pulling information from the provided patient and appointment objects where applicable. In particular, the following fields are populated from the patient and appointment objects: - Patient - Referring Provider - Subscriber Primary - Subscriber Secondary - Referral Number - Responsible Party - Guarantor Utilizing this endpoint opts you into automatic updating of the encounter when the patient or appointment is updated, assuming the encounter has not already been submitted or adjudicated. 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.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Request

This endpoint expects an object.
benefits_assigned_to_providerbooleanRequired

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.

billable_statusenumRequired

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.

Allowed values:
billing_providerobjectRequired
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.
external_idstringRequired

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.

patient_authorized_releasebooleanRequired

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.

pre_encounter_appointment_idslist of UUIDsRequired
pre_encounter_patient_idUUIDRequired
provider_accepts_assignmentbooleanRequired

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.

submission_expectationenumRequiredBeta
Describes the currently expected target form for this encounter. This effects what validations and queues the form is processed under.
Allowed values:
accident_datedateOptional

837p Loop2300 DTP*439, CMS1500 Box 15

additional_informationstringOptional

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.

admission_datedateOptional

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.

appointment_typestringOptional

Human-readable description of the appointment type (ex: “Acupuncture - Headaches”).

billing_noteslist of objectsOptional

Spot to store misc, human-readable, notes about this encounter to be used in the billing process.

clinical_noteslist of objectsOptional
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.
date_of_servicedateOptional
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.
delay_reason_codeenumOptional

837i Loop2300, CLM-1300 Box 20 Code indicating the reason why a request was delayed

discharge_datedateOptional

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.

end_date_of_servicedateOptional
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.
existing_medicationslist of objectsOptional
health_care_code_informationobjectOptional
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.
initial_referring_providerobjectOptional

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

interventionslist of objectsOptional
last_menstrual_period_datedateOptional

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.

onset_of_current_illness_or_symptom_datedateOptional

837p Loop2300 DTP*431, CMS-1500 Box 14 Required 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. OR This date is the onset of acute symptoms for the current illness or condition. For UB-04 claims, this is populated separately via occurrence codes.

patient_historieslist of objectsOptional
pay_to_addressobjectOptional
Specifies the address to which payments for the claim should be sent.
place_of_service_codeenumOptional
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).
property_casualty_claim_numberstringOptional
837p Loop2010 REF02, CMS1500 Box 11b
property_casualty_patient_identifierobjectOptional
Patient identifier for Property and Casualty claims 837p Loop 2010CA
related_causes_informationobjectOptional

Corresponds to box 10a on the CMS-1500 (Loop 2300 on 837)

rendering_providerobjectOptional

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_authorization_exception_codeenumOptional

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.

service_facilityobjectOptional
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
service_lineslist of objectsOptional
supervising_providerobjectOptional
Required when the rendering provider is supervised by a physician. If not required by this implementation guide, do not send.
synchronicityenumOptional

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.

Allowed values:
tag_idslist of stringsOptional
Names of tags that should be on the encounter.
vitalsobjectOptional
accident_state_or_province_codeenumOptionalBeta

837i-REF1000 — an optional state indicating where an accident related to the encounter occurred.

admission_hourintegerOptionalBeta

837i Loop 2300 DTP-03 Extension of the admission date with hour (0-23 integer) details.

admission_source_codeenumOptionalBeta

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.

admission_type_codeenumOptionalBeta

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.

attending_providerobjectOptionalBeta

837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has overall responsibility for the patient in institutional claims processing.

discharge_hourintegerOptionalBeta

837i Loop 2300 DTP-03 Extension of the discharge date with hour (0-23 integer) details.

discharge_statusenumOptionalBeta

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” .

external_claim_submissionobjectOptionalBeta

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).

operating_providerobjectOptionalBeta

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_providerobjectOptionalBeta

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.

schema_instanceslist of objectsOptionalBeta

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.

type_of_billobjectOptionalBeta

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.

Response

This endpoint returns an object.
benefits_assigned_to_providerboolean

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.

billable_statusenum

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.

Allowed values:
billing_providerobject
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 form or Form Locator 1 on a UB-04 claim form.
claimslist of objects
clinical_noteslist of objects
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.
created_atdatetime
The date and time the encounter was created.
diagnoseslist of objects
Contains the primary and other diagnosis health care code information objects associated with this encounter. For professional claims, these diagnoses correspond with those that are set on service lines directly, where as for institutional claims these are only associated directly with the claim itself. See also Health Care Code Information objects and corresponding apis.
encounter_idUUID
external_idstring

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.

owner_of_next_actionenum
The party who is responsible for taking the next action on an Encounter, as defined by ownership of open Tasks.
Allowed values:
patientobject
Contains the identification information of the individual receiving medical services.
patient_authorized_releaseboolean

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.

patient_historieslist of objects
patient_paymentslist of objects
provider_accepts_assignmentboolean

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.

rendering_providerobject

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.

responsible_partyenum
Defines the party to be billed with the initial balance owed on the claim.
Allowed values:
service_facilityobject
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
submission_originenum

The party who originally submitted the Claim. For Claims originating in Candid, this will be EncounterSubmissionOriginType.CANDID. For Encounters created with an external_claim_submission object, this will be EncounterSubmissionOriginType.EXTERNAL.

Allowed values:
tagslist of objects
urlstring
URL that links directly to the claim created in Candid.
schema_instanceslist of objectsBeta

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.

accident_datedate

837p Loop2300 DTP*439, CMS1500 Box 15

additional_informationstring

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.

admission_datedate

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.

appointment_typestring

Human-readable description of the appointment type (ex: “Acupuncture - Headaches”).

billing_noteslist of objects

Spot to store misc, human-readable, notes about this encounter to be used in the billing process.

claim_creation_idUUID
If the encounter was created from ingested charge captures, this is the associated Charge Capture Claim Creation Id.
claim_supplemental_informationlist of objects

Refers to Loop 2300 - Segment PWK on the 837P and 837i form. No more than 10 entries are permitted.

coding_attributionenum
The entity that performed the coding of medical services for the claim.
Allowed values:
date_of_servicedate
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.
delay_reason_codeenum

837i Loop2300, CLM-1300 Box 20 Code indicating the reason why a request was delayed

discharge_datedate

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.

end_date_of_servicedate
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.
epsdt_referralobject

Refers to Box 24H on the CMS1500 form and Loop 2300 CRC - EPSDT Referral on the 837P and 837i form

existing_medicationslist of objects
guarantorobject
Personal and contact info for the guarantor of the patient responsibility.
initial_referring_providerobject
interventionslist of objects
last_menstrual_period_datedate

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.

last_submitted_atdatetime
The date and time the encounter was last submitted to a payer.
next_responsible_partyenum

The party (payer, patient, etc.) responsible for the remainder of the balance on the claim.

onset_of_current_illness_or_symptom_datedate

837p Loop2300 DTP*431, CMS-1500 Box 14 Required 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. OR This date is the onset of acute symptoms for the current illness or condition. For UB-04 claims, this is populated separately via occurrence codes.

patient_control_numberstring

A patient control number (PCN) is a unique identifier assigned to a patient within a healthcare system or facility. It’s used to track and manage a patient’s medical records, treatments, and other healthcare-related information.

pay_to_addressobject
Specifies the address to which payments for the claim should be sent.
place_of_service_codeenum
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).
place_of_service_code_as_submittedenum
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).
prior_authorization_numberstring

Box 23 on the CMS-1500 claim form or Form Locator 63 on a UB-04 claim form.

property_casualty_claim_numberstring
837p Loop2010 REF02, CMS1500 Box 11b
property_casualty_patient_identifierobject
Patient identifier for Property and Casualty claims. 837p Loop2010CA
referral_numberstring

Refers to REF*9F on the 837p. Value cannot be greater than 50 characters.

referring_providerobject
related_causes_informationobject
secondary_payer_carrier_codestring
When Medicaid is billed as the secondary payer the Carrier Code is used to identify the primary payer. This is required for certain states.
service_authorization_exception_codeenum

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.

subscriber_primaryobject
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_secondaryobject
Contains details of the secondary insurance subscriber.
subscriber_tertiaryobject
Contains details of the tertiary insurance subscriber.
supervising_providerobject
synchronicityenum

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.

Allowed values:
vitalsobject
work_queue_idstring
work_queue_membership_activated_atdatetime
accident_state_or_province_codeenumBeta

837i-REF1000 — an optional state indicating where an accident related to the encounter occurred.

admission_hourintegerBeta

837i Loop 2300 DTP-03 Extension of the admission date with hour (0-23) details. Required for institutional submission.

admission_source_codeenumBeta

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.

admission_type_codeenumBeta

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.

attending_providerobjectBeta

837i NM1 2500 variant for Loop ID-2310. Used to indicate the individual whom has overall responsibility for the patient in institutional claims processing.

discharge_hourintegerBeta

837i Loop 2300 DTP-03 Extension of the discharge date with hour (0-23) details.

discharge_statusenumBeta

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_providerobjectBeta

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_providerobjectBeta

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.

submission_expectationenumBeta

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.

Allowed values:
type_of_billobjectBeta

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.

Errors

403
Unauthorized Error
404
Entity Not Found Error
422
Encounter External ID Uniqueness Error
422
Encounter Patient Control Number Uniqueness Error
422
HTTP Request Validation Error
422
HTTP Request Validations Error
422
Payer Plan Group Payer Does Not Match Insurance Card HTTP Error
422
Schema Instance Validation HTTP Failure
422
Unprocessable Entity Error