> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.joincandidhealth.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.joincandidhealth.com/_mcp/server. # Create encounter pre-service run POST https://api.joincandidhealth.com/api/pre-service/v1/runs/encounter Content-Type: application/json Submit a representation of an encounter to the Candid rules engine. Note that this encounter will not be created in Candid. Returns a run\_id that can be polled via GET /runs/\{run\_id} to retrieve the results once complete. Reference: https://docs.joincandidhealth.com/api-reference/pre-service-rules/v-1/create-encounter-run ## Authentication - OAuth2 — send the obtained token as `Authorization: Bearer ` ## Servers - `https://api.joincandidhealth.com` (Production, default) - `https://api-staging.joincandidhealth.com` (Staging) - `https://sandbox-api.joincandidhealth.com` (CandidSandbox) - `https://staging-api.joincandidhealth.com` (CandidStaging) - `http://localhost:5050` (Local) ## Request ### Body (application/json) This endpoint expects an object. - `entity` (PreServiceEncounterCreate, required) — The encounter to evaluate against the rules engine. - `pipeline_id` (string, required) — Identifies the set of rules to run against the encounter. - `enabled_rule_ids` (list of UUID, required) — IDs of disabled rules to force-enable for this run (e.g. for testing new rules). - `disabled_rule_ids` (list of UUID, required) — IDs of enabled rules to force-disable for this run (e.g., to "override" or skip certain rules). - `idempotency_key` (string, required) — Prevents multiple rule runs from being dispatched in response to duplicate requests. ## Response ### 202 - `UUID` ## Errors ### 403 Unauthorized Error - `errorName` ("UnauthorizedError", required) - `content` (UnauthorizedErrorMessage, required) ### 422 Unprocessable Entity Error - `errorName` ("UnprocessableEntityError", required) - `content` (UnprocessableEntityErrorMessage, required) ## Types ### PreServiceEncounterCreate The encounter to run pre-service rules against. This should represent the state of the encounter/claim in the source system. In an Electronic Health Record (EHR) system, this might be a claim, billing note, or other entity. A client should transform the source system entity into this encounter shape in order to run Candid rules. - `external_id` (string, required) — The client's internal ID for this encounter, or the relevant entity in their source system. Returned in the run result so the client can match results back to their own records. - `patient_authorized_release` (boolean, required) — Whether this patient has authorized the release of medical information for billing purposes. Box 12 on the CMS-1500 claim form or Form Locator 52 on a UB-04 claim form. - `benefits_assigned_to_provider` (boolean, required) — Whether this patient has authorized insurance payments to be made to the provider. Box 13 on the CMS-1500 claim form or Form Locator 53 on a UB-04 claim form. - `provider_accepts_assignment` (boolean, required) — Whether the provider has accepted the patient's authorization for insurance payments. Box 27 on the CMS-1500 claim form. - `patient` (PatientCreate, required) — The patient receiving the service. - `responsible_party` (enum, required) — Defines the party responsible for the initial balance. Use SELF_PAY for self-pay encounters. - Allowed values: `INSURANCE_PAY`, `SELF_PAY`, `UNKNOWN` - `billing_provider` (BillingProvider, required) — The provider or business entity submitting the claim. Box 33 on the CMS-1500 claim form. - `date_of_service` (date, required) — Date formatted as YYYY-MM-DD. Box 24a on the CMS-1500 claim form. If service occurred over a range of dates, this should be the start date. Must be on or after 2010-01-01. - `service_lines` (list of UniversalServiceLineCreate, required) — Service lines for this encounter. On professional encounters each line needs a procedure_code. revenue_code must be 4 characters. diagnosis_pointers must be unique and reference diagnoses submitted in health_care_code_information. - `health_care_code_information` (HealthCareCodeInformationCreate, required) — Health care code information associated with this encounter, including diagnoses, vitals, procedures, occurrences, reason for visit, and other code-related fields. Must include principal_diagnosis with principal_diagnosis_code_qualifier ABK. When responsible_party is INSURANCE_PAY, ICD-10 diagnosis codes must be valid. - `submission_expectation` (enum, required) — Describes the currently expected target form for this encounter (professional or institutional). - Allowed values: `TARGET_PROFESSIONAL`, `TARGET_INSTITUTIONAL` - `end_date_of_service` (date, optional) — Date formatted as YYYY-MM-DD. If omitted, assumed to be a single-day encounter. Must be on or after date_of_service. - `pay_to_address` (StreetAddressLongZip, optional) — Specifies the address to which payments for the claim should be sent. - `referring_provider` (ReferringProvider, optional) — The final provider who referred the services that were rendered. All physicians who order services or refer Medicare beneficiaries must report this data. - `supervising_provider` (SupervisingProvider, optional) — Required when the rendering provider is supervised by a physician. - `service_facility` (EncounterServiceFacilityBase, optional) — The location where the medical service was rendered. Box 32 on the CMS-1500 claim form. - `subscriber_primary` (SubscriberCreate, optional) — Required when responsible_party is INSURANCE_PAY. Not required for self-pay encounters, but include it when available. - `subscriber_secondary` (SubscriberCreate, optional) — Include when available, even for self-pay claims. - `prior_authorization_number` (string, optional) — Box 23 on the CMS-1500 claim form or Form Locator 63 on a UB-04 claim form. - `place_of_service_code` (enum, optional) — Box 24B on the CMS-1500 claim form. 02 for telemedicine, 11 for in-person. Not used on UB-04 or 837i claim forms. - Allowed values: `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` - `rendering_provider` (RenderingProvider, optional) — The practitioner performing the service. For telehealth services, the rendering provider performs the visit or asynchronous communication. Required unless submission_expectation is TARGET_INSTITUTIONAL. - `initial_referring_provider` (InitialReferringProvider, optional) — 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. - `service_facility_id` (UUID, optional) — The ID of an existing Organization Service Facility to use for this encounter. Note: this field is accepted for API parity but is not resolved during pre-service evaluation; provide service_facility directly if the service facility data is needed for rules. - `subscriber_tertiary` (SubscriberCreate, optional) — Include when available, even for self-pay claims. - `guarantor` (GuarantorCreate, optional) — Personal and contact info for the guarantor of the patient responsibility. - `clinical_notes` (list of ClinicalNoteCategoryCreate, optional) — Holds a collection of clinical observations made by healthcare providers during patient encounters. - `billing_notes` (list of BillingNoteBase, optional) — Spot to store misc, human-readable, notes about this encounter to be used in the billing process. - `patient_histories` (list of PatientHistoryCategory, optional) - `tag_ids` (list of string, optional) — Names of tags that should be on the encounter. - `referral_number` (string, optional) — Refers to REF*9F on the 837p and 837i. Value cannot be greater than 50 characters. - `epsdt_referral` (EPSDTReferral, optional) — Refers to Box 24H on the CMS1500 form and Loop 2300 CRC - EPSDT Referral on the 837P and 837i form. - `claim_supplemental_information` (list of ClaimSupplementalInformation, optional) — Refers to Loop 2300 - Segment PWK on the 837P and 837i forms. No more than 10 entries are permitted. - `secondary_payer_carrier_code` (string, optional) — 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` (RelatedCausesInformationCreate, optional) — Corresponds to box 10a on the CMS-1500 (Loop 2300 on 837). - `property_casualty_claim_number` (string, optional) — 837p Loop2010 REF02, CMS1500 Box 11b. - `accident_date` (date, optional) — 837p Loop2300 DTP*439, CMS1500 Box 15. - `initial_treatment_date` (date, optional) — 837p Loop2300 DTP*454, CMS1500 Box 15. - `property_casualty_patient_identifier` (PropertyCasualtyPatientIdentifierCreate, optional) — Patient identifier for Property and Casualty claims. 837p Loop 2010CA. - `schema_instances` (list of SchemaInstance, optional) — 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. - `attending_provider` (RenderingProvider, optional) — 837i Loop ID-2310. The individual with overall responsibility for the patient. Used in institutional claims processing. - `treating_provider` (TreatingProvider, optional) — The treating provider is the provider who treats the patient. This is only supported for professional encounters. - `operating_provider` (RenderingProvider, optional) — 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` (RenderingProvider, optional) — 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. - `external_claim_submission` (ExternalClaimSubmissionCreate, optional) — To be included for claims that have been submitted outside of Candid. - `admission_hour` (integer, optional) — 837i Loop 2300 DTP-03 Extension of the admission date with hour (0-23 integer) details. - `admission_type_code` (enum, optional) — 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. - Allowed values: `1`, `2`, `3`, `4`, `5`, `9` - `admission_source_code` (enum, optional) — 837i Loop 2300 CL1-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. - Allowed values: `1`, `2`, `4`, `5`, `6`, `8`, `9`, `D`, `E`, `F`, `G` - `discharge_hour` (integer, optional) — 837i Loop 2300 DTP-03 Extension of the discharge date with hour (0-23 integer) details. - `discharge_status` (enum, optional) — 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". - Allowed values: `01`, `02`, `03`, `04`, `05`, `06`, `07`, `09`, `20`, `21`, `30`, `40`, `41`, `42`, `43`, `50`, `51`, `61`, `62`, `63`, `64`, `65`, `66`, `69`, `70`, `81`, `82`, `83`, `84`, `85`, `86`, `87`, `88`, `89`, `90`, `91`, `92`, `93`, `94`, `95` - `type_of_bill` (TypeOfBillCompositeUpdate, optional) — Four digit code used in institutional forms to indicate the type of bill. Professional forms are not required to submit this attribute. - `accident_state_or_province_code` (enum, optional) — 837i-REF1000 -- an optional state indicating where an accident related to the encounter occurred. - Allowed values: `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`, `FC` ### UnauthorizedErrorMessage - `message` (string, optional) ### UnprocessableEntityErrorMessage - `message` (string, optional) ### PatientCreate - `address` (StreetAddressShortZip, required) — Box 5 on the CMS-1500 claim form or Form Locator 9 on a UB-04 claim form. - `date_of_birth` (date, required) — 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) - `external_id` (string, required) — The ID used to identify this individual in your system. For example, your internal patient ID or an EHR patient ID. - `first_name` (string, required) - `gender` (enum, required) - Allowed values: `male`, `female`, `other`, `not_given`, `unknown` - `last_name` (string, required) - `auto_charge_consent` (boolean, optional) — Defaults to false - `email` (string, optional) - `email_consent` (boolean, optional) — Defaults to false - `non_insurance_payers_info` (list of PatientNonInsurancePayerInfoCreate, optional) - `phone_consent` (boolean, optional) — Defaults to false - `phone_numbers` (list of PhoneNumber, optional) - `non_insurance_payers` (list of UUID, optional, deprecated) ### BillingProvider 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. - `address` (StreetAddressLongZip, required) - `npi` (string, required) - `tax_id` (string, required) — If the provider has a contract with insurance, this must be the same tax ID given to the payer on an IRS W-9 form completed during contracting. - `first_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `last_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `organization_name` (string, optional) — If the provider is an organization, this should be set instead of first + last name - `provider_commercial_license_type` (enum, optional) — 837i Loop2010BB G2 Provider Commercial Number - Allowed values: `0`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`, `I` - `secondary_identification` (BillingProviderSecondaryIdentification, optional) — Only one of provider_commercial_license_type or secondary_identification may be provided 837i Loop2010BB G2 Secondary Identification - `taxonomy_code` (string, optional) ### UniversalServiceLineCreate - `quantity` (string, required) — String representation of a Decimal that can be parsed by most libraries. For professional claims, a ServiceLine quantity cannot contain more than one digit of precision (Example: 1.1 is valid, 1.11 is not). For institutional claims, a ServiceLine quantity cannot contain more than three decimal digits of precision. - `units` (enum, required) - Allowed values: `MJ`, `UN` - `charge_amount_cents` (integer, optional) — The total amount charged for this service line, factoring in quantity. If procedure_code is updated and this is not, the system will attempt to set it based on chargemasters entries and the service line’s quantity. For example, if a single unit has an entry of 100 cents and 2 units were rendered, the charge_amount_cents will be set to 200, if there is no chargemaster entry, it will default to the amount set in this field. - `date_of_service` (date, optional) - `description` (string, optional) — A free-form description to clarify the related data elements and their content. Maps to SV1-01, C003-07 on a 837-P and SV2-02, C003-07 on a 837-I form. - `diagnosis_pointers` (list of integer, optional) — Indices (zero-indexed) of all the diagnoses this service line references - `drug_identification` (DrugIdentification, optional) - `end_date_of_service` (date, optional) - `external_id` (string, optional) — An external identifier for this service line. This is not used in the EDI 837, but can be used to identify the service line in external systems. This field should not contain PHI. Must be unique on a given claim. - `has_epsdt_indicator` (boolean, optional) — Maps to SV1-11 on the 837-P and Box 24H on the CMS-1500. If the value is true, the box will be populated with "Y". Otherwise, the box will not be populated. - `has_family_planning_indicator` (boolean, optional) — Maps to SV1-12 on the 837-P and Box 24I on the CMS-1500. If the value is true, the box will be populated with "Y". Otherwise, the box will not be populated. - `modifiers` (list of enum, optional) - Allowed values: `AV`, `AU`, `AW`, `AY`, `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `32`, `33`, `47`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `57`, `58`, `59`, `62`, `63`, `66`, `73`, `74`, `76`, `77`, `78`, `79`, `80`, `81`, `82`, `90`, `91`, `92`, `93`, `95`, `96`, `97`, `99`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `A7`, `A8`, `A9`, `AA`, `AB`, `AD`, `AE`, `AF`, `AG`, `AH`, `AI`, `AJ`, `AK`, `AM`, `AO`, `AP`, `AQ`, `AR`, `AS`, `AT`, `AZ`, `BA`, `BL`, `BO`, `BP`, `BR`, `BU`, `CA`, `CB`, `CC`, `CD`, `CE`, `CF`, `CG`, `CH`, `CI`, `CJ`, `CK`, `CL`, `CM`, `CN`, `CR`, `CS`, `CT`, `CO`, `CQ`, `DA`, `E1`, `E2`, `E3`, `E4`, `EA`, `EB`, `EC`, `ED`, `EE`, `EJ`, `EM`, `EP`, `ER`, `ET`, `EV`, `EX`, `EY`, `F1`, `F2`, `F3`, `F4`, `F5`, `F6`, `F7`, `F8`, `F9`, `FA`, `FB`, `FC`, `FP`, `FQ`, `FR`, `FS`, `FT`, `FX`, `FY`, `G0`, `G1`, `G2`, `G3`, `G4`, `G5`, `G6`, `G7`, `G8`, `G9`, `GA`, `GB`, `GC`, `GE`, `GF`, `GG`, `GH`, `GJ`, `GK`, `GL`, `GM`, `GN`, `GO`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GV`, `GW`, `GX`, `GY`, `GZ`, `HA`, `HB`, `HC`, `HD`, `HE`, `HF`, `HG`, `HH`, `HI`, `HJ`, `HK`, `HL`, `HM`, `HN`, `HO`, `HP`, `HQ`, `HR`, `HS`, `HT`, `HU`, `HV`, `HW`, `HX`, `HY`, `HZ`, `J1`, `J2`, `J3`, `J4`, `J5`, `JA`, `JB`, `JC`, `JD`, `JE`, `JG`, `JW`, `JZ`, `K0`, `K1`, `K2`, `K3`, `K4`, `KA`, `KB`, `KC`, `KD`, `KE`, `KF`, `KG`, `KH`, `KI`, `KJ`, `KK`, `KL`, `KM`, `KN`, `KO`, `KP`, `KQ`, `KR`, `KS`, `KT`, `KU`, `KV`, `KW`, `KX`, `KY`, `KZ`, `LC`, `LD`, `LL`, `LM`, `LR`, `LS`, `LT`, `LU`, `M2`, `MA`, `MB`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MS`, `N1`, `N2`, `N3`, `NB`, `NR`, `NU`, `P1`, `P2`, `P3`, `P4`, `P5`, `P6`, `PA`, `PB`, `PC`, `PD`, `PI`, `PL`, `PM`, `PN`, `PO`, `PS`, `PT`, `Q0`, `Q1`, `Q2`, `Q3`, `Q4`, `Q5`, `Q6`, `Q7`, `Q8`, `Q9`, `QA`, `QB`, `QC`, `QD`, `QE`, `QF`, `QG`, `QH`, `QJ`, `QK`, `QL`, `QM`, `QN`, `QP`, `QQ`, `QR`, `QS`, `QT`, `QW`, `QX`, `QY`, `QZ`, `RA`, `RB`, `RC`, `RD`, `RE`, `RI`, `RR`, `RT`, `SA`, `SB`, `SC`, `SD`, `SE`, `SF`, `SG`, `SH`, `SJ`, `SL`, `SM`, `SN`, `SQ`, `SS`, `ST`, `SU`, `SV`, `SW`, `SY`, `T1`, `T2`, `T3`, `T4`, `T5`, `T6`, `T7`, `T8`, `T9`, `TA`, `TB`, `TC`, `TD`, `TE`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TP`, `TQ`, `TR`, `TS`, `TT`, `TU`, `TV`, `TW`, `U1`, `U2`, `U3`, `U4`, `U5`, `U6`, `U7`, `U8`, `U9`, `UA`, `UB`, `UC`, `UD`, `UE`, `UF`, `UG`, `UH`, `UJ`, `UK`, `UN`, `UP`, `UQ`, `UR`, `US`, `V1`, `V2`, `V3`, `W1`, `W2`, `W3`, `WC`, `WH`, `X4`, `XE`, `XP`, `XS`, `XU`, `XY`, `ZZ` - `note` (string, optional) — Maps to NTE02 loop 2400 on the EDI 837. - `ordering_provider` (OrderingProvider, optional) — Required when the service or supply was ordered by a provider who is different than the rendering provider for this service line. If not required by this implementation guide, do not send. - `place_of_service_code` (enum, optional) — 837p Loop2300, SV105. This enum is not used or required in 837i claims. If your organization does not intend to submit claims with a different place of service at the service line level, this field should not be populated. 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). - Allowed values: `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` - `prior_authorization_number` (string, optional) — Prior authorization number for this service line. Maps to the appropriate REF segment on Loop 2400 of the EDI 837p. This is not used for institutional claims (EDI 837i). - `procedure_code` (string, optional) - `revenue_code` (string, optional) — A 4 digit code that specifies facility department or type of service arrangement for institutional service line items (837i). This code is not required for professional claim billing (837p). - `test_results` (list of TestResult, optional) — Contains a list of test results. Test result types may map to MEA-02 on the 837-P (ex: Hemoglobin, Hematocrit). This is unused by 837-i and ignored for institutional service lines. No more than 5 MEA-02 test results may be submitted per service line. ### HealthCareCodeInformationCreate - `principal_diagnosis` (PrincipalDiagnosisNew, optional) — This corresponds to BK or ABK code qualifier values. - `other_diagnosis_information` (list of OtherDiagnosisInformationNew, optional) - `admitting_diagnosis` (AdmittingDiagnosisNew, optional) — This object only applies to 837i institutional claim forms. - `patient_reasons_for_visit` (list of PatientReasonForVisitNew, optional) — This object only applies to 837i institutional claim forms. - `external_causes_of_injury` (list of ExternalCauseOfInjuryNew, optional) — This object only applies to 837i institutional claim forms. - `diagnosis_related_groups` (DiagnosisRelatedGroupNew, optional) — This object only applies to 837i institutional claim forms. - `principal_procedure` (PrincipalProcedureInformationNew, optional) — This object only applies to 837i institutional claim forms. - `other_procedure_information` (list of OtherProcedureInformationNew, optional) — This object only applies to 837i institutional claim forms. - `occurrence_span_information` (list of OccurrenceSpanInformationNew, optional) — This object only applies to 837i institutional claim forms. - `occurrence_information` (list of OccurrenceInformationNew, optional) — This object only applies to 837i institutional claim forms. - `treatment_code_information` (list of TreatmentCodeInformationNew, optional) — This object only applies to 837i institutional claim forms. - `value_information` (list of ValueInformationNew, optional) — This object only applies to 837i institutional claim forms. - `condition_information` (list of ConditionInformationNew, optional) — This object only applies to 837i institutional claim forms. ### StreetAddressLongZip - `address1` (string, required) - `city` (string, required) - `state` (enum, required) - Allowed values: `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`, `FC` - `zip_code` (string, required) — 5-digit zip code - `zip_plus_four_code` (string, required) — 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4 - `address2` (string, optional) ### ReferringProvider - `npi` (string, required) — A National Provider Identifier is a unique 10-digit identification number issued to health care providers in the United States - `address` (StreetAddressLongZip, optional) - `first_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `last_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `organization_name` (string, optional) — If the provider is an organization, this should be set instead of first + last name - `secondary_identification` (ReferringProviderSecondaryIdentification, optional) - `taxonomy_code` (string, optional) - `qualifier` (enum, optional, deprecated) — Deprecated. This field will be removed in a future release. - Allowed values: `DQ`, `DN`, `DK`, `P3` ### SupervisingProvider - `npi` (string, required) — A National Provider Identifier is a unique 10-digit identification number issued to health care providers in the United States - `address` (StreetAddressLongZip, optional) - `first_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `last_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `organization_name` (string, optional) — If the provider is an organization, this should be set instead of first + last name - `secondary_identification` (SupervisingProviderSecondaryIdentification, optional) - `taxonomy_code` (string, optional) ### EncounterServiceFacilityBase 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. - `organization_name` (string, required) - `address` (StreetAddressLongZip, required) — 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. - `npi` (string, optional) — 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. - `secondary_identification` (string, optional) — 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` (string, optional) — The associated mammography certification number for this service facility. This is a 6 digit code assigned by the FDA. ### SubscriberCreate - `first_name` (string, required) - `gender` (enum, required) - Allowed values: `male`, `female`, `other`, `not_given`, `unknown` - `insurance_card` (InsuranceCardCreate, required) — Please reference our [Payer Information](https://docs.joincandidhealth.com/introduction/payer-information) documentation for more details on how to populate the `insurance_card` fields. - `last_name` (string, required) - `patient_relationship_to_subscriber_code` (enum, required) - Allowed values: `01`, `04`, `05`, `07`, `10`, `15`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `29`, `32`, `33`, `36`, `39`, `40`, `41`, `43`, `53`, `G8` - `address` (StreetAddressShortZip, optional) - `date_of_birth` (date, optional) ### RenderingProvider - `npi` (string, required) — A National Provider Identifier is a unique 10-digit identification number issued to health care providers in the United States - `address` (StreetAddressLongZip, optional) - `first_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `last_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `organization_name` (string, optional) — If the provider is an organization, this should be set instead of first + last name - `secondary_identification` (ProviderSecondaryIdentification, optional) — Only one of provider_commercial_license_type or secondary_identification may be provided 837i Loop2310BB G2 Secondary Identification - `taxonomy_code` (string, optional) ### InitialReferringProvider - `npi` (string, required) — A National Provider Identifier is a unique 10-digit identification number issued to health care providers in the United States - `address` (StreetAddressLongZip, optional) - `first_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `last_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `organization_name` (string, optional) — If the provider is an organization, this should be set instead of first + last name - `qualifier` (enum, optional) - Allowed values: `DQ`, `DN`, `DK`, `P3` - `secondary_identification` (ReferringProviderSecondaryIdentification, optional) - `taxonomy_code` (string, optional) ### GuarantorCreate - `address` (StreetAddressShortZip, required) - `external_id` (string, required) - `first_name` (string, required) - `last_name` (string, required) - `auto_charge_consent` (boolean, optional) — Defaults to false - `date_of_birth` (date, optional) - `email` (string, optional) - `email_consent` (boolean, optional) — Defaults to false - `phone_consent` (boolean, optional) — Defaults to false - `phone_numbers` (list of PhoneNumber, optional) ### ClinicalNoteCategoryCreate - `category` (enum, required) - Allowed values: `clinical`, `care_plan`, `diagnoses`, `vitals`, `physical_exam`, `review_of_systems`, `medical_decisions`, `history_of_present_illness`, `patient_info`, `chief_complaint`, `health_record`, `consent`, `procedure`, `time_in_appointment` - `notes` (list of ClinicalNote, required) ### BillingNoteBase - `text` (string, required) — Empty string not allowed. ### PatientHistoryCategory - `category` (enum, required) - Allowed values: `present_illness`, `medical`, `family`, `social` - `questions` (list of IntakeQuestion, required) — Must contain at least one item. ### EPSDTReferral - `condition_indicator1` (enum, required) - Allowed values: `AV`, `NU`, `S2`, `ST` - `condition_indicator2` (enum, optional) - Allowed values: `AV`, `NU`, `S2`, `ST` - `condition_indicator3` (enum, optional) - Allowed values: `AV`, `NU`, `S2`, `ST` ### ClaimSupplementalInformation - `attachment_report_type_code` (enum, required) - Allowed values: `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `13`, `15`, `21`, `A3`, `A4`, `AM`, `AS`, `B2`, `B3`, `B4`, `BR`, `BS`, `BT`, `CB`, `CK`, `CT`, `D2`, `DA`, `DB`, `DG`, `DJ`, `DS`, `EB`, `HC`, `HR`, `I5`, `IR`, `LA`, `M1`, `MT`, `NN`, `OB`, `OC`, `OD`, `OE`, `OX`, `OZ`, `P4`, `P5`, `PE`, `PN`, `PO`, `PQ`, `PY`, `PZ`, `RB`, `RR`, `RT`, `RX`, `SG`, `V5`, `XP` - `attachment_transmission_code` (enum, required) - Allowed values: `AA`, `BM`, `EL`, `FX` - `attachment_control_number` (string, optional) ### RelatedCausesInformationCreate - `related_causes_code_1` (enum, required) - Allowed values: `AA`, `AB`, `AP`, `EM`, `OA`, `ZZ` - `related_causes_code_2` (enum, optional) - Allowed values: `AA`, `AB`, `AP`, `EM`, `OA`, `ZZ` - `state_or_province_code` (string, optional) ### PropertyCasualtyPatientIdentifierCreate - `property_casualty_patient_identifier` (string, required) — Represents REF02 on the EDI 837 Loop 2010CA Property and Casualty Patient Identifier segment. Value cannot exceed 50 characters - `property_casualty_patient_identifier_qualifier` (enum, required) — Represents REF01 on the EDI 837 Loop 2010CA Property and Casualty Patient Identifier segment. Valid values include 1W (Member Identification Number) and SY (Social Security Number). - Allowed values: `1W`, `SY` ### SchemaInstance - `schema_id` (UUID, required) — The schema to which the content must adhere. - `content` (map from string to any, required) — A set of key-value pairs that adhere to the naming and type convention of the schema. Not all keys in the schema must be included, but attaching any key that does not exist in the schema or attaching a key with the incorrect value type will result in errors. ### TreatingProvider The treating provider for professional encounters. Unlike other provider types, the treating provider has an optional NPI and no organization_name field. - `first_name` (string, required) - `last_name` (string, required) - `npi` (string, optional) — A National Provider Identifier is a unique 10-digit identification number issued to health care providers in the United States - `taxonomy_code` (string, optional) - `address` (StreetAddressLongZip, optional) - `license_type` (enum, optional) — The license type of the treating provider (e.g., MD, NP, PA, LCSW). - Allowed values: `MD`, `NP`, `PA`, `LMFT`, `LCPC`, `LCSW`, `PMHNP`, `FNP`, `LPCC`, `DO`, `RD`, `SLP`, `APRN`, `LPC`, `PHD`, `PSYD`, `LMSW`, `LMHC`, `OTHER_MASTERS`, `BCBA`, `UNKNOWN`, `RPH`, `PHT`, `LAC`, `LMT`, `DC`, `ND`, `MA`, `PT`, `IBCLC`, `RN`, `DPT`, `LCMHC`, `CNM`, `RNFA`, `ACSW`, `APC`, `BCABA`, `BHA`, `OD`, `DPM`, `DA`, `DDS`, `DEH`, `DMD`, `PTA`, `LCADC`, `LCAT`, `LCMHCS`, `LCMHCA`, `LCSWA`, `LICSW`, `LISW`, `LMFTS`, `LMFTA`, `LPCI`, `LSCSW`, `MHCA`, `MHT`, `RBT`, `RCSWI`, `RHMCI`, `LPN`, `OTD`, `OMS`, `MFTA`, `APCC`, `DNP`, `AGNPBC`, `ANP`, `FNPPP`, `LCSWR`, `ALC`, `RMFTI`, `LAMFT`, `LPCA`, `LSWI`, `CSW`, `CPC`, `LGMFT`, `LLPC`, `PLPC`, `PLMFT`, `LMHCA`, `CIT`, `CT`, `MFT`, `LSW`, `PLMHP`, `PCMSW`, `LMHP`, `OTR/L`, `RPA`, `COTA`, `CRNP`, `SLP-CF`, `NP-C`, `PA-C`, `AMFT`, `CDN`, `CGC`, `CNS`, `MDPHD`, `AuD`, `ATC`, `LAT`, `OTA`, `LSSP`, `SLPA`, `EdD`, `SWT`, `IMFT`, `RT` ### ExternalClaimSubmissionCreate - `claim_created_at` (datetime, required) — When the claim was created in the external system. - `patient_control_number` (string, required) — The Patient Control Number sent on the claim to the payer. To guarantee compatibility with all payers, this field must consist only of uppercase letters and numbers and be no more than 14 characters long. - `submission_records` (list of ClaimSubmissionRecordCreate, required) — A successful claim submission record will be created for each value provided. An empty list may be provided for cases where the claim originated in an external system but was never submitted to a payer. ### TypeOfBillCompositeUpdate A type of bill can either be seen as a composition of structured parts, or as a literal string. This union represents the potential to express a type of bill either as one of those two shapes. Passing a string, this update will be seen as a complete 4 digit code, along with a padding code 0, that should match a valid composition. Passing as a structure, the update will be seen as three parts and will be joined together by the server to represent a valid composition for you. Which you use depends upon whether you are "passing through" coded information or making a decision about its structure explicitly. - `type`: `raw_code` - `value` (string, required) - `type`: `composite_codes` - `frequency_code` (enum, required) — The FL04 Institutional frequency code for the bill. The fourth digit of the composite code. - Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`, `I`, `J`, `K`, `M`, `O`, `P`, `Q`, `X`, `Y`, `Z` - `type_of_care` (enum, required) — The FL04 Institutional type of care code for the bill. The third digit of the composite code. - Allowed values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` - `type_of_facility` (enum, required) — The FL04 Institutional type of facility code for the bill. The second digit of the composite code. - Allowed values: `1`, `2`, `3`, `4`, `6`, `7`, `8` ### StreetAddressShortZip - `address1` (string, required) - `city` (string, required) - `state` (enum, required) - Allowed values: `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`, `FC` - `zip_code` (string, required) — 5-digit zip code - `address2` (string, optional) - `zip_plus_four_code` (string, optional) — 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4 ### PatientNonInsurancePayerInfoCreate - `non_insurance_payer_id` (UUID, required) - `member_id` (string, optional) - `clinical_trial_info` (list of PatientClinicalTrialInfoCreate, optional) ### PhoneNumber - `number` (string, required) - `type` (enum, required) - Allowed values: `Home`, `Mobile`, `Work` ### BillingProviderSecondaryIdentification - `reference_identification` (string, required) — Represents REF02 on the EDI 837 Loop 2010BB Billing Provider Secondary Identification segment. Value cannot exceed 50 characters - `reference_identification_qualifier` (enum, optional) — Represents REF01 on the EDI 837 Loop 2010BB Billing Provider Secondary Identification segment. Valid values include G2 (Provider Commercial Number) and LU (Location Number). Defaults to G2 if not set. - Allowed values: `G2`, `LU` ### DrugIdentification - `service_id_qualifier` (enum, required) - Allowed values: `EN`, `EO`, `HI`, `N4`, `ON`, `UK`, `UP` - `national_drug_code` (string, required) - `national_drug_unit_count` (string, required) - `measurement_unit_code` (enum, required) - Allowed values: `ML`, `UN`, `GR`, `F2`, `ME` - `link_sequence_number` (string, optional) - `pharmacy_prescription_number` (string, optional) - `conversion_formula` (string, optional) - `drug_description` (string, optional) ### OrderingProvider - `npi` (string, required) — A National Provider Identifier is a unique 10-digit identification number issued to health care providers in the United States - `address` (StreetAddressLongZip, optional) - `first_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `last_name` (string, optional) — If the provider is an individual, this should be set instead of organization name - `organization_name` (string, optional) — If the provider is an organization, this should be set instead of first + last name - `taxonomy_code` (string, optional) ### TestResult - `value` (double, required) - `result_type` (enum, required) - Allowed values: `HEMATOCRIT`, `HEMOGLOBIN`, `LDL`, `VITAMIN_D` ### PrincipalDiagnosisNew This corresponds to BK or ABK code qualifier values. - `principal_diagnosis_code_qualifier` (enum, required) - Allowed values: `BK`, `ABK` - `primary_diagnosis_code` (string, required) - `present_on_admission_indicator` (enum, optional) - Allowed values: `Y`, `N`, `U`, `W`, `1` ### OtherDiagnosisInformationNew This corresponds to BF and ABF code qualifier values. - `other_diagnosis_code_qualifier` (enum, required) - Allowed values: `BF`, `ABF` - `other_diagnosis` (string, required) - `present_on_admission_indicator` (enum, optional) - Allowed values: `Y`, `N`, `U`, `W`, `1` ### AdmittingDiagnosisNew This corresponds to BJ or ABJ code qualifier values. - `admitting_diagnosis_code_qualifier` (enum, required) - Allowed values: `BJ`, `ABJ` - `admitting_diagnosis_code` (string, required) ### PatientReasonForVisitNew This corresponds to PR or APR code qualifier values. - `patient_reason_for_visit_code_qualifier` (enum, required) - Allowed values: `PR`, `APR` - `patient_reason_for_visit` (string, required) ### ExternalCauseOfInjuryNew This corresponds to BN or ABN code qualifier values. - `external_cause_of_injury_code_qualifier` (enum, required) - Allowed values: `BN`, `ABN` - `external_cause_of_injury_code` (string, required) - `present_on_admission_indicator` (enum, optional) - Allowed values: `Y`, `N`, `U`, `W`, `1` ### DiagnosisRelatedGroupNew This corresponds to DR code qualifier values. - `diagnosis_related_group_code_qualifier` (enum, required) - Allowed values: `DR` - `diagnosis_related_group_code` (string, required) ### PrincipalProcedureInformationNew This correspond to BBR, BR, and CAH code qualifier values. - `principal_procedure_code_qualifier` (enum, required) - Allowed values: `BBR`, `BR`, `CAH` - `principal_procedure_code` (string, required) - `procedure_date` (date, required) — An [RFC 3339, section 5.6 datetime](https://ijmacd.github.io/rfc3339-iso8601/). For example, 2017-07-21T17:32:28Z. In practice, only the date portion of this is used for claim submission, so midnight time is fine. ### OtherProcedureInformationNew This corresponds to the BBQ or BQ code qualifier values. - `other_procedure_code_qualifier` (enum, required) - Allowed values: `BBQ`, `BQ` - `other_procedure_code` (string, required) - `other_procedure_date` (date, required) — An [RFC 3339, section 5.6 datetime](https://ijmacd.github.io/rfc3339-iso8601/). For example, 2017-07-21T17:32:28Z. In practice, only the date portion of this is used for claim submission, so midnight time is fine. ### OccurrenceSpanInformationNew This corresponds to the BI code qualifier value. - `occurrence_span_code_qualifier` (enum, required) - Allowed values: `BI` - `occurrence_span_code` (enum, required) - Allowed values: `70`, `71`, `72`, `73`, `74`, `75`, `76`, `77`, `78`, `80`, `81`, `82`, `M0`, `M1`, `M2`, `M3`, `M4` - `occurrence_span_date` (RD8Date, required) ### OccurrenceInformationNew This corresponds to the BH code qualifier value. - `occurrence_code_qualifier` (enum, required) - Allowed values: `BH` - `occurrence_code` (enum, required) - Allowed values: `01`, `02`, `03`, `04`, `05`, `06`, `09`, `10`, `11`, `12`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `33`, `34`, `35`, `36`, `37`, `38`, `39`, `40`, `41`, `42`, `43`, `44`, `45`, `46`, `47`, `50`, `51`, `52`, `54`, `55`, `56`, `61`, `62`, `A1`, `A2`, `A3`, `A4`, `B1`, `B2`, `B3`, `C1`, `C2`, `C3` - `occurrence_date` (date, required) — An [RFC 3339, section 5.6 datetime](https://ijmacd.github.io/rfc3339-iso8601/). For example, 2017-07-21T17:32:28Z. In practice, only the date portion of this is used for claim submission, so midnight time is fine. ### TreatmentCodeInformationNew This corresponds to the TC code qualifier value. - `treatment_code_qualifier` (enum, required) - Allowed values: `TC` - `treatment_code` (string, required) ### ValueInformationNew This corresponds to the BE code qualifier value. - `value_code_qualifier` (enum, required) - Allowed values: `BE` - `value_code` (enum, required) - Allowed values: `01`, `02`, `04`, `05`, `06`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `33`, `34`, `35`, `37`, `38`, `39`, `40`, `41`, `42`, `43`, `44`, `45`, `46`, `47`, `48`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `57`, `58`, `59`, `60`, `61`, `66`, `67`, `68`, `69`, `80`, `81`, `82`, `83`, `84`, `85`, `87`, `89`, `90`, `91`, `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `A7`, `A8`, `A9`, `AA`, `AB`, `B1`, `B2`, `B3`, `B7`, `BA`, `BB`, `C1`, `C2`, `C3`, `C7`, `CA`, `CB`, `D3`, `D4`, `D5`, `D6`, `FC`, `FD`, `G8`, `P1`, `P2`, `P3`, `Y1`, `Y2`, `Y3`, `Y4`, `Y5` - `value_code_amount` (string, required) — String representation of a Decimal that can be parsed by most libraries. ### ConditionInformationNew This corresponds to the BG code qualifier value. - `condition_code_qualifier` (enum, required) - Allowed values: `BG` - `condition_code` (enum, required) — FL 18-28 - Condition Codes Source: UB-04 Manual 2025, Pages 64-81 (FL18-28, Pages 1-18) Excludes codes designated as "Payer Codes" or "FOR PUBLIC HEALTH DATA REPORTING ONLY" unless usage on claims is indicated. - Allowed values: `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `33`, `34`, `35`, `36`, `37`, `38`, `39`, `40`, `41`, `42`, `43`, `44`, `45`, `46`, `47`, `48`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `57`, `58`, `59`, `60`, `61`, `66`, `67`, `68`, `69`, `70`, `71`, `72`, `73`, `74`, `75`, `76`, `77`, `78`, `79`, `80`, `81`, `82`, `83`, `84`, `85`, `86`, `87`, `88`, `89`, `90`, `91`, `92`, `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, `A7`, `A9`, `AA`, `AB`, `AC`, `AD`, `AE`, `AF`, `AG`, `AH`, `AI`, `AJ`, `AK`, `AL`, `AM`, `AN`, `B0`, `B1`, `B2`, `B3`, `B4`, `BP`, `C1`, `C2`, `C3`, `C4`, `C5`, `C6`, `C7`, `D0`, `D1`, `D2`, `D3`, `D4`, `D5`, `D6`, `D7`, `D8`, `D9`, `DR(a)`, `E0`, `G0`, `H0`, `H2`, `H3`, `H4`, `H5`, `P1`, `P7`, `R1`, `R2`, `R3`, `R4`, `R5`, `R6`, `R7`, `R8`, `R9`, `W0`, `W2`, `W3`, `W4`, `W5` ### ReferringProviderSecondaryIdentification - `reference_identification` (string, required) - `reference_identification_qualifier` (enum, required) - Allowed values: `0B`, `1G`, `G2` ### SupervisingProviderSecondaryIdentification - `reference_identification` (string, required) - `reference_identification_qualifier` (enum, required) - Allowed values: `0B`, `1G`, `G2`, `LU` ### InsuranceCardCreate - `member_id` (string, required) - `payer_id` (string, required) - `payer_name` (string, required) - `emr_payer_crosswalk` (enum, optional) — Set to PAYER_PLAN_GROUP to use Payer Plans for automatic payer resolution. See Payer Information documentation for details. - Allowed values: `HEALTHIE`, `CANVAS`, `WAYSTAR`, `PAYER_PLAN_GROUP` - `group_number` (string, optional) — Box 11 on the CMS-1500 claim form. - `image_url_back` (string, optional) - `image_url_front` (string, optional) - `insurance_type` (enum, optional) — Code identifying the type of insurance policy within a specific insurance program (X12 008020 Element 1336) - Allowed values: `01`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `41`, `42`, `43`, `47`, `AP`, `C1`, `CO`, `CP`, `D`, `DB`, `E`, `EP`, `FF`, `GP`, `HA`, `HB`, `HD`, `HG`, `HM`, `HN`, `HP`, `HS`, `IN`, `IP`, `LC`, `LD`, `LI`, `LT`, `M`, `MA`, `MB`, `MC`, `MD`, `ME`, `MF`, `MH`, `MI`, `MJ`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MR`, `MT`, `MV`, `OA`, `OT`, `PE`, `PL`, `PP`, `PR`, `PS`, `QM`, `RP`, `SP`, `TF`, `U`, `WC`, `WU` - `payer_address` (StreetAddressLongZip, optional) - `payer_plan_group_id` (UUID, optional) - `payer_plan_group_name` (string, optional) — When using emr_payer_crosswalk set to PAYER_PLAN_GROUP, specify the payer plan name here. See Payer Information documentation for details. - `plan_name` (string, optional) — Box 11c on the CMS-1500 claim form. - `plan_type` (enum, optional) - Allowed values: `09`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `AM`, `BL`, `CH`, `CI`, `DS`, `FI`, `HM`, `LM`, `MA`, `MB`, `MC`, `OF`, `TV`, `VA`, `WC`, `ZZ` - `rx_bin` (string, optional) - `rx_pcn` (string, optional) ### ProviderSecondaryIdentification - `reference_identification` (string, required) — Represents REF02 on the EDI 837 Loop 2010BB Billing Provider Secondary Identification segment. Value cannot exceed 50 characters - `reference_identification_qualifier` (enum, optional) — Represents REF01 on the EDI 837 Loop 2010BB Provider Secondary Identification segment. - Allowed values: `0B`, `1G`, `G2`, `LU` ### ClinicalNote - `text` (string, required) - `author_name` (string, required) - `timestamp` (datetime, required) - `author_npi` (string, optional) ### IntakeQuestion - `id` (string, required) - `text` (string, required) - `responses` (list of IntakeResponseAndFollowUps, optional) ### ClaimSubmissionRecordCreate Data about each external submission. - `submitted_at` (datetime, required) — When the claim was submitted to the payer. - `claim_frequency_code` (enum, optional) - Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`, `I`, `J`, `K`, `M`, `O`, `P`, `Q`, `X`, `Y`, `Z` - `payer_responsibility` (enum, optional) - Allowed values: `primary`, `secondary` - `intended_submission_medium` (enum, optional) — The medium by which the claim was submitted to the payer: paper or electronic. If omitted, defaults to electronic. - Allowed values: `paper`, `electronic` ### PatientClinicalTrialInfoCreate - `clinical_trial_id` (UUID, required) - `clinical_trial_arm` (string, optional) ### RD8Date - `start` (date, required) - `end` (date, required) ### IntakeResponseAndFollowUps - `response` (string, optional) - `follow_ups` (list of IntakeFollowUp, optional) ### IntakeFollowUp - `id` (string, required) - `text` (string, required) - `response` (string, optional) ## Examples **Request** ```json { "entity": { "external_id": "enc-123", "patient_authorized_release": true, "benefits_assigned_to_provider": true, "provider_accepts_assignment": true, "patient": { "address": { "address1": "1 Main St", "city": "Fairfax", "state": "VA", "zip_code": "22031" }, "date_of_birth": "1960-01-01", "external_id": "p-456", "first_name": "Jane", "gender": "female", "last_name": "Doe" }, "responsible_party": "INSURANCE_PAY", "billing_provider": { "address": { "address1": "1 Main St", "city": "Fairfax", "state": "VA", "zip_code": "22031", "zip_plus_four_code": "4634" }, "npi": "1558375857", "tax_id": "202265068", "organization_name": "Example Clinic" }, "date_of_service": "2026-10-15", "service_lines": [ { "quantity": "1", "units": "UN", "charge_amount_cents": 20600, "diagnosis_pointers": [ 0 ], "procedure_code": "99213" } ], "health_care_code_information": { "principal_diagnosis": { "principal_diagnosis_code_qualifier": "ABK", "primary_diagnosis_code": "Z01.411" } }, "submission_expectation": "TARGET_PROFESSIONAL", "subscriber_primary": { "first_name": "Jane", "gender": "female", "insurance_card": { "member_id": "123456789", "payer_id": "12345", "payer_name": "Example Payer" }, "last_name": "Doe", "patient_relationship_to_subscriber_code": "18" }, "rendering_provider": { "npi": "1234567893", "first_name": "Ada", "last_name": "Lovelace" } }, "pipeline_id": "pre-service-claim-athena", "enabled_rule_ids": [], "disabled_rule_ids": [], "idempotency_key": "enc-123-run-1" } ``` **Response** ```json "0192a6f4-7c1e-7b3a-9d2e-5f8a1c3b4d6e" ``` **SDK Code** ```python import requests url = "https://api.joincandidhealth.com/api/pre-service/v1/runs/encounter" payload = { "entity": { "external_id": "enc-123", "patient_authorized_release": True, "benefits_assigned_to_provider": True, "provider_accepts_assignment": True, "patient": { "address": { "address1": "1 Main St", "city": "Fairfax", "state": "VA", "zip_code": "22031" }, "date_of_birth": "1960-01-01", "external_id": "p-456", "first_name": "Jane", "gender": "female", "last_name": "Doe" }, "responsible_party": "INSURANCE_PAY", "billing_provider": { "address": { "address1": "1 Main St", "city": "Fairfax", "state": "VA", "zip_code": "22031", "zip_plus_four_code": "4634" }, "npi": "1558375857", "tax_id": "202265068", "organization_name": "Example Clinic" }, "date_of_service": "2026-10-15", "service_lines": [ { "quantity": "1", "units": "UN", "charge_amount_cents": 20600, "diagnosis_pointers": [0], "procedure_code": "99213" } ], "health_care_code_information": { "principal_diagnosis": { "principal_diagnosis_code_qualifier": "ABK", "primary_diagnosis_code": "Z01.411" } }, "submission_expectation": "TARGET_PROFESSIONAL", "subscriber_primary": { "first_name": "Jane", "gender": "female", "insurance_card": { "member_id": "123456789", "payer_id": "12345", "payer_name": "Example Payer" }, "last_name": "Doe", "patient_relationship_to_subscriber_code": "18" }, "rendering_provider": { "npi": "1234567893", "first_name": "Ada", "last_name": "Lovelace" } }, "pipeline_id": "pre-service-claim-athena", "enabled_rule_ids": [], "disabled_rule_ids": [], "idempotency_key": "enc-123-run-1" } headers = { "Authorization": ".", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.joincandidhealth.com/api/pre-service/v1/runs/encounter'; const options = { method: 'POST', headers: {Authorization: '.', 'Content-Type': 'application/json'}, body: '{"entity":{"external_id":"enc-123","patient_authorized_release":true,"benefits_assigned_to_provider":true,"provider_accepts_assignment":true,"patient":{"address":{"address1":"1 Main St","city":"Fairfax","state":"VA","zip_code":"22031"},"date_of_birth":"1960-01-01","external_id":"p-456","first_name":"Jane","gender":"female","last_name":"Doe"},"responsible_party":"INSURANCE_PAY","billing_provider":{"address":{"address1":"1 Main St","city":"Fairfax","state":"VA","zip_code":"22031","zip_plus_four_code":"4634"},"npi":"1558375857","tax_id":"202265068","organization_name":"Example Clinic"},"date_of_service":"2026-10-15","service_lines":[{"quantity":"1","units":"UN","charge_amount_cents":20600,"diagnosis_pointers":[0],"procedure_code":"99213"}],"health_care_code_information":{"principal_diagnosis":{"principal_diagnosis_code_qualifier":"ABK","primary_diagnosis_code":"Z01.411"}},"submission_expectation":"TARGET_PROFESSIONAL","subscriber_primary":{"first_name":"Jane","gender":"female","insurance_card":{"member_id":"123456789","payer_id":"12345","payer_name":"Example Payer"},"last_name":"Doe","patient_relationship_to_subscriber_code":"18"},"rendering_provider":{"npi":"1234567893","first_name":"Ada","last_name":"Lovelace"}},"pipeline_id":"pre-service-claim-athena","enabled_rule_ids":[],"disabled_rule_ids":[],"idempotency_key":"enc-123-run-1"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.joincandidhealth.com/api/pre-service/v1/runs/encounter" payload := strings.NewReader("{\n \"entity\": {\n \"external_id\": \"enc-123\",\n \"patient_authorized_release\": true,\n \"benefits_assigned_to_provider\": true,\n \"provider_accepts_assignment\": true,\n \"patient\": {\n \"address\": {\n \"address1\": \"1 Main St\",\n \"city\": \"Fairfax\",\n \"state\": \"VA\",\n \"zip_code\": \"22031\"\n },\n \"date_of_birth\": \"1960-01-01\",\n \"external_id\": \"p-456\",\n \"first_name\": \"Jane\",\n \"gender\": \"female\",\n \"last_name\": \"Doe\"\n },\n \"responsible_party\": \"INSURANCE_PAY\",\n \"billing_provider\": {\n \"address\": {\n \"address1\": \"1 Main St\",\n \"city\": \"Fairfax\",\n \"state\": \"VA\",\n \"zip_code\": \"22031\",\n \"zip_plus_four_code\": \"4634\"\n },\n \"npi\": \"1558375857\",\n \"tax_id\": \"202265068\",\n \"organization_name\": \"Example Clinic\"\n },\n \"date_of_service\": \"2026-10-15\",\n \"service_lines\": [\n {\n \"quantity\": \"1\",\n \"units\": \"UN\",\n \"charge_amount_cents\": 20600,\n \"diagnosis_pointers\": [\n 0\n ],\n \"procedure_code\": \"99213\"\n }\n ],\n \"health_care_code_information\": {\n \"principal_diagnosis\": {\n \"principal_diagnosis_code_qualifier\": \"ABK\",\n \"primary_diagnosis_code\": \"Z01.411\"\n }\n },\n \"submission_expectation\": \"TARGET_PROFESSIONAL\",\n \"subscriber_primary\": {\n \"first_name\": \"Jane\",\n \"gender\": \"female\",\n \"insurance_card\": {\n \"member_id\": \"123456789\",\n \"payer_id\": \"12345\",\n \"payer_name\": \"Example Payer\"\n },\n \"last_name\": \"Doe\",\n \"patient_relationship_to_subscriber_code\": \"18\"\n },\n \"rendering_provider\": {\n \"npi\": \"1234567893\",\n \"first_name\": \"Ada\",\n \"last_name\": \"Lovelace\"\n }\n },\n \"pipeline_id\": \"pre-service-claim-athena\",\n \"enabled_rule_ids\": [],\n \"disabled_rule_ids\": [],\n \"idempotency_key\": \"enc-123-run-1\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", ".") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.joincandidhealth.com/api/pre-service/v1/runs/encounter") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = '.' request["Content-Type"] = 'application/json' request.body = "{\n \"entity\": {\n \"external_id\": \"enc-123\",\n \"patient_authorized_release\": true,\n \"benefits_assigned_to_provider\": true,\n \"provider_accepts_assignment\": true,\n \"patient\": {\n \"address\": {\n \"address1\": \"1 Main St\",\n \"city\": \"Fairfax\",\n \"state\": \"VA\",\n \"zip_code\": \"22031\"\n },\n \"date_of_birth\": \"1960-01-01\",\n \"external_id\": \"p-456\",\n \"first_name\": \"Jane\",\n \"gender\": \"female\",\n \"last_name\": \"Doe\"\n },\n \"responsible_party\": \"INSURANCE_PAY\",\n \"billing_provider\": {\n \"address\": {\n \"address1\": \"1 Main St\",\n \"city\": \"Fairfax\",\n \"state\": \"VA\",\n \"zip_code\": \"22031\",\n \"zip_plus_four_code\": \"4634\"\n },\n \"npi\": \"1558375857\",\n \"tax_id\": \"202265068\",\n \"organization_name\": \"Example Clinic\"\n },\n \"date_of_service\": \"2026-10-15\",\n \"service_lines\": [\n {\n \"quantity\": \"1\",\n \"units\": \"UN\",\n \"charge_amount_cents\": 20600,\n \"diagnosis_pointers\": [\n 0\n ],\n \"procedure_code\": \"99213\"\n }\n ],\n \"health_care_code_information\": {\n \"principal_diagnosis\": {\n \"principal_diagnosis_code_qualifier\": \"ABK\",\n \"primary_diagnosis_code\": \"Z01.411\"\n }\n },\n \"submission_expectation\": \"TARGET_PROFESSIONAL\",\n \"subscriber_primary\": {\n \"first_name\": \"Jane\",\n \"gender\": \"female\",\n \"insurance_card\": {\n \"member_id\": \"123456789\",\n \"payer_id\": \"12345\",\n \"payer_name\": \"Example Payer\"\n },\n \"last_name\": \"Doe\",\n \"patient_relationship_to_subscriber_code\": \"18\"\n },\n \"rendering_provider\": {\n \"npi\": \"1234567893\",\n \"first_name\": \"Ada\",\n \"last_name\": \"Lovelace\"\n }\n },\n \"pipeline_id\": \"pre-service-claim-athena\",\n \"enabled_rule_ids\": [],\n \"disabled_rule_ids\": [],\n \"idempotency_key\": \"enc-123-run-1\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.joincandidhealth.com/api/pre-service/v1/runs/encounter") .header("Authorization", ".") .header("Content-Type", "application/json") .body("{\n \"entity\": {\n \"external_id\": \"enc-123\",\n \"patient_authorized_release\": true,\n \"benefits_assigned_to_provider\": true,\n \"provider_accepts_assignment\": true,\n \"patient\": {\n \"address\": {\n \"address1\": \"1 Main St\",\n \"city\": \"Fairfax\",\n \"state\": \"VA\",\n \"zip_code\": \"22031\"\n },\n \"date_of_birth\": \"1960-01-01\",\n \"external_id\": \"p-456\",\n \"first_name\": \"Jane\",\n \"gender\": \"female\",\n \"last_name\": \"Doe\"\n },\n \"responsible_party\": \"INSURANCE_PAY\",\n \"billing_provider\": {\n \"address\": {\n \"address1\": \"1 Main St\",\n \"city\": \"Fairfax\",\n \"state\": \"VA\",\n \"zip_code\": \"22031\",\n \"zip_plus_four_code\": \"4634\"\n },\n \"npi\": \"1558375857\",\n \"tax_id\": \"202265068\",\n \"organization_name\": \"Example Clinic\"\n },\n \"date_of_service\": \"2026-10-15\",\n \"service_lines\": [\n {\n \"quantity\": \"1\",\n \"units\": \"UN\",\n \"charge_amount_cents\": 20600,\n \"diagnosis_pointers\": [\n 0\n ],\n \"procedure_code\": \"99213\"\n }\n ],\n \"health_care_code_information\": {\n \"principal_diagnosis\": {\n \"principal_diagnosis_code_qualifier\": \"ABK\",\n \"primary_diagnosis_code\": \"Z01.411\"\n }\n },\n \"submission_expectation\": \"TARGET_PROFESSIONAL\",\n \"subscriber_primary\": {\n \"first_name\": \"Jane\",\n \"gender\": \"female\",\n \"insurance_card\": {\n \"member_id\": \"123456789\",\n \"payer_id\": \"12345\",\n \"payer_name\": \"Example Payer\"\n },\n \"last_name\": \"Doe\",\n \"patient_relationship_to_subscriber_code\": \"18\"\n },\n \"rendering_provider\": {\n \"npi\": \"1234567893\",\n \"first_name\": \"Ada\",\n \"last_name\": \"Lovelace\"\n }\n },\n \"pipeline_id\": \"pre-service-claim-athena\",\n \"enabled_rule_ids\": [],\n \"disabled_rule_ids\": [],\n \"idempotency_key\": \"enc-123-run-1\"\n}") .asString(); ``` ```php request('POST', 'https://api.joincandidhealth.com/api/pre-service/v1/runs/encounter', [ 'body' => '{ "entity": { "external_id": "enc-123", "patient_authorized_release": true, "benefits_assigned_to_provider": true, "provider_accepts_assignment": true, "patient": { "address": { "address1": "1 Main St", "city": "Fairfax", "state": "VA", "zip_code": "22031" }, "date_of_birth": "1960-01-01", "external_id": "p-456", "first_name": "Jane", "gender": "female", "last_name": "Doe" }, "responsible_party": "INSURANCE_PAY", "billing_provider": { "address": { "address1": "1 Main St", "city": "Fairfax", "state": "VA", "zip_code": "22031", "zip_plus_four_code": "4634" }, "npi": "1558375857", "tax_id": "202265068", "organization_name": "Example Clinic" }, "date_of_service": "2026-10-15", "service_lines": [ { "quantity": "1", "units": "UN", "charge_amount_cents": 20600, "diagnosis_pointers": [ 0 ], "procedure_code": "99213" } ], "health_care_code_information": { "principal_diagnosis": { "principal_diagnosis_code_qualifier": "ABK", "primary_diagnosis_code": "Z01.411" } }, "submission_expectation": "TARGET_PROFESSIONAL", "subscriber_primary": { "first_name": "Jane", "gender": "female", "insurance_card": { "member_id": "123456789", "payer_id": "12345", "payer_name": "Example Payer" }, "last_name": "Doe", "patient_relationship_to_subscriber_code": "18" }, "rendering_provider": { "npi": "1234567893", "first_name": "Ada", "last_name": "Lovelace" } }, "pipeline_id": "pre-service-claim-athena", "enabled_rule_ids": [], "disabled_rule_ids": [], "idempotency_key": "enc-123-run-1" }', 'headers' => [ 'Authorization' => '.', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.joincandidhealth.com/api/pre-service/v1/runs/encounter"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "."); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"entity\": {\n \"external_id\": \"enc-123\",\n \"patient_authorized_release\": true,\n \"benefits_assigned_to_provider\": true,\n \"provider_accepts_assignment\": true,\n \"patient\": {\n \"address\": {\n \"address1\": \"1 Main St\",\n \"city\": \"Fairfax\",\n \"state\": \"VA\",\n \"zip_code\": \"22031\"\n },\n \"date_of_birth\": \"1960-01-01\",\n \"external_id\": \"p-456\",\n \"first_name\": \"Jane\",\n \"gender\": \"female\",\n \"last_name\": \"Doe\"\n },\n \"responsible_party\": \"INSURANCE_PAY\",\n \"billing_provider\": {\n \"address\": {\n \"address1\": \"1 Main St\",\n \"city\": \"Fairfax\",\n \"state\": \"VA\",\n \"zip_code\": \"22031\",\n \"zip_plus_four_code\": \"4634\"\n },\n \"npi\": \"1558375857\",\n \"tax_id\": \"202265068\",\n \"organization_name\": \"Example Clinic\"\n },\n \"date_of_service\": \"2026-10-15\",\n \"service_lines\": [\n {\n \"quantity\": \"1\",\n \"units\": \"UN\",\n \"charge_amount_cents\": 20600,\n \"diagnosis_pointers\": [\n 0\n ],\n \"procedure_code\": \"99213\"\n }\n ],\n \"health_care_code_information\": {\n \"principal_diagnosis\": {\n \"principal_diagnosis_code_qualifier\": \"ABK\",\n \"primary_diagnosis_code\": \"Z01.411\"\n }\n },\n \"submission_expectation\": \"TARGET_PROFESSIONAL\",\n \"subscriber_primary\": {\n \"first_name\": \"Jane\",\n \"gender\": \"female\",\n \"insurance_card\": {\n \"member_id\": \"123456789\",\n \"payer_id\": \"12345\",\n \"payer_name\": \"Example Payer\"\n },\n \"last_name\": \"Doe\",\n \"patient_relationship_to_subscriber_code\": \"18\"\n },\n \"rendering_provider\": {\n \"npi\": \"1234567893\",\n \"first_name\": \"Ada\",\n \"last_name\": \"Lovelace\"\n }\n },\n \"pipeline_id\": \"pre-service-claim-athena\",\n \"enabled_rule_ids\": [],\n \"disabled_rule_ids\": [],\n \"idempotency_key\": \"enc-123-run-1\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": ".", "Content-Type": "application/json" ] let parameters = [ "entity": [ "external_id": "enc-123", "patient_authorized_release": true, "benefits_assigned_to_provider": true, "provider_accepts_assignment": true, "patient": [ "address": [ "address1": "1 Main St", "city": "Fairfax", "state": "VA", "zip_code": "22031" ], "date_of_birth": "1960-01-01", "external_id": "p-456", "first_name": "Jane", "gender": "female", "last_name": "Doe" ], "responsible_party": "INSURANCE_PAY", "billing_provider": [ "address": [ "address1": "1 Main St", "city": "Fairfax", "state": "VA", "zip_code": "22031", "zip_plus_four_code": "4634" ], "npi": "1558375857", "tax_id": "202265068", "organization_name": "Example Clinic" ], "date_of_service": "2026-10-15", "service_lines": [ [ "quantity": "1", "units": "UN", "charge_amount_cents": 20600, "diagnosis_pointers": [0], "procedure_code": "99213" ] ], "health_care_code_information": ["principal_diagnosis": [ "principal_diagnosis_code_qualifier": "ABK", "primary_diagnosis_code": "Z01.411" ]], "submission_expectation": "TARGET_PROFESSIONAL", "subscriber_primary": [ "first_name": "Jane", "gender": "female", "insurance_card": [ "member_id": "123456789", "payer_id": "12345", "payer_name": "Example Payer" ], "last_name": "Doe", "patient_relationship_to_subscriber_code": "18" ], "rendering_provider": [ "npi": "1234567893", "first_name": "Ada", "last_name": "Lovelace" ] ], "pipeline_id": "pre-service-claim-athena", "enabled_rule_ids": [], "disabled_rule_ids": [], "idempotency_key": "enc-123-run-1" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.joincandidhealth.com/api/pre-service/v1/runs/encounter")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```