Create encounter from pre-encounter patient and appointment

Beta
POST

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
  • Prior Authorization Number
  • Appointment Type
  • 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.

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.
billable_status"BILLABLE" or "NOT_BILLABLE"Required
Allowed values: BILLABLENOT_BILLABLE

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.

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 form.
diagnoseslist of objectsRequired
Ideally, this field should contain no more than 12 diagnoses. However, more diagnoses may be submitted at this time, and coders will later prioritize the 12 that will be submitted to the payor.
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.
place_of_service_codeenumRequired

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.

pre_encounter_appointment_idUUIDRequired
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.
rendering_providerobjectRequired
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.
additional_informationstringOptional
Defines additional information on the claim needed by the payer. Box 19 on the CMS-1500 claim form.
admission_datedateOptional

837p Loop2300 DTP*435, CMS-1500 Box 18 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.

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

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
initial_referring_providerobjectOptional
The second iteration of Loop ID-2310. 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.
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.

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.

patient_historieslist of objectsOptional
pay_to_addressobjectOptional
Specifies the address to which payments for the claim should be sent.
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. 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.
service_lineslist of objectsOptional

Each service line must be linked to a diagnosis. Concretely, service_line.diagnosis_pointersmust contain at least one entry which should be in bounds of the diagnoses list field.

supervising_providerobjectOptional
Required when the rendering provider is supervised by a physician. If not required by this implementation guide, do not send.
synchronicity"Synchronous" or "Asynchronous"Optional
Allowed values: SynchronousAsynchronous
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.
tag_idslist of stringsOptional
Names of tags that should be on the encounter.
vitalsobjectOptional
external_claim_submissionobjectOptionalBeta

This field is in beta. 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).

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.

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.
billable_status"BILLABLE" or "NOT_BILLABLE"
Allowed values: BILLABLENOT_BILLABLE

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.

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.
claimslist of objects
clinical_noteslist of objects
Holds a collection of clinical observations made by healthcare providers during patient encounters.
diagnoseslist of objects
Ideally, this field should contain no more than 12 diagnoses. However, more diagnoses may be submitted at this time, and coders will later prioritize the 12 that will be submitted to the payor.
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
Allowed values: CANDIDCUSTOMERCODERNONE
The party who is responsible for taking the next action on an Encounter, as defined by ownership of open Tasks.
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.
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.
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
Allowed values: INSURANCE_PAYSELF_PAYUNKNOWN
Defines the party to be billed with the initial balance owed on the claim.
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. 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.
submission_origin"CANDID" or "EXTERNAL"
Allowed values: CANDIDEXTERNAL

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.

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.
additional_informationstringOptional
Defines additional information on the claim needed by the payer. Box 19 on the CMS-1500 claim form.
admission_datedateOptional

837p Loop2300 DTP*435, CMS-1500 Box 18 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.
coding_attributionenumOptional
Allowed values: CANDIDCUSTOMERTCNPJF
The entity that performed the coding of medical services for the claim.
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. 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.

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
guarantorobjectOptional
Personal and contact info for the guarantor of the patient responsibility.
initial_referring_providerobjectOptional
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.

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.

patient_control_numberstringOptional
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_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. Line-level place of service is not currently supported. 02 for telemedicine, 11 for in-person. Full list here.

place_of_service_code_as_submittedenumOptional

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.

prior_authorization_numberstringOptional
Box 23 on the CMS-1500 claim form.
referring_providerobjectOptional
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.

subscriber_primaryobjectOptional

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_secondaryobjectOptional
Contains details of the secondary insurance subscriber.
supervising_providerobjectOptional
synchronicity"Synchronous" or "Asynchronous"Optional
Allowed values: SynchronousAsynchronous
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.
vitalsobjectOptional
work_queue_idstringOptional
work_queue_membership_activated_atdatetimeOptional

Errors

Built with