---
title: "Update institutional or professional encounter"
method: PATCH
path: "/api/encounters/v4/{encounter_id}/universal"
tags: ["v4"]
---

# Update institutional or professional encounter

`PATCH /api/encounters/v4/{encounter_id}/universal`

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.

## Path parameters

- `encounter_id` string, uuid, required

## Headers

- `Authorization` string, required

## Request body

- TypeEncountersUniversalUniversalEncounterUpdate
  - `benefits_assigned_to_provider` boolean — Whether this patient has authorized insurance payments to be made to you, not them. If false, patient may receive reimbursement. Box 13 on the CMS-1500 claim form or Form Locator 53 on a UB-04 claim form.
  - `prior_authorization_number` V4PriorAuthorizationNumber — unresolved $ref
  - `external_id` string
  - `date_of_service` string, date — Date formatted as YYYY-MM-DD; eg: 2019-08-24. This date must be the local date in the timezone where the service occurred. Box 24a on the CMS-1500 claim form or Form Locator 45 on the UB-04 claim form. If service occurred over a range of dates, this should be the start date. If service lines have distinct date_of_service values, updating the encounter's date_of_service will fail. If all service line date_of_service values are the same, updating the encounter's date_of_service will update all service line date_of_service values.
  - `tag_ids` TypeTagsTagId[] — Names of tags that should be on the encounter. Note all tags on encounter will be overridden with this list.
  - `billable_status` V4BillableStatusType — unresolved $ref
  - `responsible_party` V4ResponsiblePartyType — unresolved $ref
  - `provider_accepts_assignment` boolean — Whether you have accepted the patient's authorization for insurance payments to be made to you, not them. Box 27 on the CMS-1500 claim form. There is no exact equivalent of this field on a UB-04 claim, however contributes to the concept of Form Locator 53.
  - `synchronicity` V4SynchronicityType — unresolved $ref
  - `place_of_service_code` '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' — Box 24B on the CMS-1500 claim form. Line-level place of service is not currently supported. 02 for telemedicine, 11 for in-person. Full list here: https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set
  - `appointment_type` string — Human-readable description of the appointment type (ex: "Acupuncture - Headaches").
  - `end_date_of_service` string, date — Date formatted as YYYY-MM-DD; eg: 2019-08-25. This date must be the local date in the timezone where the service occurred. If omitted, the Encounter is assumed to be for a single day. Must not be temporally before the date_of_service field. If service lines have distinct end_date_of_service values, updating the encounter's end_date_of_service will fail. If all service line end_date_of_service values are the same, updating the encounter's end_date_of_service will update all service line date_of_service values.
  - `additional_information` string — Defines additional information on the claim needed by the payer. Box 19 on the CMS-1500 claim form or Form Locator 80 on a UB-04 claim form.
  - `service_authorization_exception_code` V4ServiceAuthorizationExceptionCode — unresolved $ref
  - `admission_date` string, date — 837p Loop2300 DTP*435, CMS-1500 Box 18 or UB-04 Form Locator 12. Required on all ambulance claims when the patient was known to be admitted to the hospital. OR Required on all claims involving inpatient medical visits.
  - `discharge_date` string, date — 837p Loop2300 DTP*096, CMS-1500 Box 18 Required for inpatient claims when the patient was discharged from the facility and the discharge date is known. Not used on an institutional claim.
  - `onset_of_current_illness_or_symptom_date` string, date — 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.
  - `last_menstrual_period_date` string, date — 837p Loop2300 DTP*484, CMS-1500 Box 14 Required when, in the judgment of the provider, the services on this claim are related to the patient's pregnancy.de This field is populated separately via occurrence codes for UB-04 claim forms.
  - `delay_reason_code` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '15' | '16' | '17' — Code indicating the reason why a request was delayed
  - `patient_authorized_release` boolean — Whether this patient has authorized the release of medical information for billing purpose. Box 12 on the CMS-1500 claim form or Form Locator 52 on a UB-04 claim form.
  - `referral_number` string — Refers to REF*9F on the 837p. Value cannot be greater than 50 characters.
  - `secondary_payer_carrier_code` string — When Medicaid is billed as the secondary payer the Carrier Code is used to identify the primary payer. This is required for certain states.
  - `epsdt_referral` V4EPSDTReferral — unresolved $ref
  - `clinical_notes` V4ClinicalNoteCategoryCreate[] — 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. — unresolved $ref
  - `claim_supplemental_information` V4ClaimSupplementalInformation[] — Refers to Loop 2300 - Segment PWK on the 837P and 837i form. No more than 10 entries are permitted. — unresolved $ref
  - `schema_instances` V1SchemaInstance[] — Key-value pairs that must adhere to a schema created via the Custom Schema API. Multiple schema instances cannot be created for the same schema on an encounter. Updating schema instances utilizes PUT semantics, so the schema instances on the encounter will be set to whatever inputs are provided. If null is provided as an input, then the encounter's schema instances will be cleared. — unresolved $ref
  - `existing_medications` V4Medication[] — Existing medications that should be on the encounter. Note all current existing medications on encounter will be overridden with this list. — unresolved $ref
  - `guarantor` V1GuarantorUpdate — unresolved $ref
  - `subscriber_primary` TypeIndividualSubscriberCreate
    - `first_name` string, required
    - `last_name` string, required
    - `gender` 'male' | 'female' | 'other' | 'not_given' | 'unknown', required
    - `patient_relationship_to_subscriber_code` '01' | '04' | '05' | '07' | '10' | '15' | '17' | '18' | '19' | '20' | '21' | '22' | '23' | '24' | '29' | '32' | '33' | '36' | '39' | '40' | '41' | '43' | '53' | 'G8', required
    - `date_of_birth` string, date
    - `address` TypeCommonsStreetAddressShortZip
      - `address1` string, required
      - `address2` string
      - `city` string, required
      - `state` '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', required
      - `zip_code` string, required — 5-digit zip code
      - `zip_plus_four_code` string — 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4
    - `insurance_card` V2InsuranceCardCreate, required — unresolved $ref
  - `subscriber_secondary` TypeIndividualSubscriberCreate
    - `first_name` string, required
    - `last_name` string, required
    - `gender` 'male' | 'female' | 'other' | 'not_given' | 'unknown', required
    - `patient_relationship_to_subscriber_code` '01' | '04' | '05' | '07' | '10' | '15' | '17' | '18' | '19' | '20' | '21' | '22' | '23' | '24' | '29' | '32' | '33' | '36' | '39' | '40' | '41' | '43' | '53' | 'G8', required
    - `date_of_birth` string, date
    - `address` TypeCommonsStreetAddressShortZip
      - `address1` string, required
      - `address2` string
      - `city` string, required
      - `state` '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', required
      - `zip_code` string, required — 5-digit zip code
      - `zip_plus_four_code` string — 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4
    - `insurance_card` V2InsuranceCardCreate, required — unresolved $ref
  - `subscriber_tertiary` TypeIndividualSubscriberCreate
    - `first_name` string, required
    - `last_name` string, required
    - `gender` 'male' | 'female' | 'other' | 'not_given' | 'unknown', required
    - `patient_relationship_to_subscriber_code` '01' | '04' | '05' | '07' | '10' | '15' | '17' | '18' | '19' | '20' | '21' | '22' | '23' | '24' | '29' | '32' | '33' | '36' | '39' | '40' | '41' | '43' | '53' | 'G8', required
    - `date_of_birth` string, date
    - `address` TypeCommonsStreetAddressShortZip
      - `address1` string, required
      - `address2` string
      - `city` string, required
      - `state` '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', required
      - `zip_code` string, required — 5-digit zip code
      - `zip_plus_four_code` string — 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4
    - `insurance_card` V2InsuranceCardCreate, required — unresolved $ref
  - `pay_to_address` TypeCommonsStreetAddressLongZip
    - `address1` string, required
    - `address2` string
    - `city` string, required
    - `state` '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', required
    - `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
  - `initial_referring_provider` V2InitialReferringProviderUpdate — unresolved $ref
  - `referring_provider` V2ReferringProviderUpdate — unresolved $ref
  - `patient` TypeIndividualPatientUpdate
    - `first_name` string
    - `last_name` string
    - `gender` 'male' | 'female' | 'other' | 'not_given' | 'unknown'
    - `external_id` string — The ID used to identify this individual in your system. For example, your internal patient ID or an EHR patient ID.
    - `date_of_birth` string, date — Box 3 on the CMS-1500 claim form or Form Locator 10 on a UB-04 claim form. The date format should be in ISO 8601 date; formatted YYYY-MM-DD (i.e. 2012-02-01)
    - `address` TypeCommonsStreetAddressShortZip
      - `address1` string, required
      - `address2` string
      - `city` string, required
      - `state` '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', required
      - `zip_code` string, required — 5-digit zip code
      - `zip_plus_four_code` string — 4-digit zip add-on code https://en.wikipedia.org/wiki/ZIP_Code#ZIP+4
    - `phone_numbers` TypeCommonsPhoneNumber[]
      - `number` string, required
      - `type` 'Home' | 'Mobile' | 'Work', required
    - `phone_consent` boolean
    - `email` string
    - `email_consent` boolean
    - `auto_charge_consent` boolean
    - `non_insurance_payers` V1NonInsurancePayerId[] — On update, we will replace the existing list of non-insurance payers with the new list if populated. — unresolved $ref
    - `non_insurance_payers_info` TypeIndividualPatientNonInsurancePayerInfoCreate[] — On update, we will replace the existing list of non-insurance payers with the new list if populated.
      - `non_insurance_payer_id` V1NonInsurancePayerId, required — unresolved $ref
      - `member_id` string
      - `clinical_trial_info` TypeIndividualPatientClinicalTrialInfoCreate[]
        - `clinical_trial_arm` string
        - `clinical_trial_id` string, uuid, required
  - `rendering_provider` V2RenderingProviderUpdate — unresolved $ref
  - `service_facility` TypeServiceFacilityEncounterServiceFacilityUpdate
    - `organization_name` string
    - `npi` string — An NPI specific to the service facility if applicable, i.e. if it has one and is not under the billing provider's NPI. Box 32 section (a) of the CMS-1500 claim form.
    - `address` TypeCommonsStreetAddressLongZip
      - `address1` string, required
      - `address2` string
      - `city` string, required
      - `state` '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', required
      - `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
    - `secondary_identification` string — 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 — The associated mammography certification number for this service facility. This is a 6 digit code assigned by the FDA.
  - `supervising_provider` V2SupervisingProviderUpdate — unresolved $ref
  - `treating_provider` V2TreatingProviderUpdate — unresolved $ref
  - `billing_provider` V2BillingProviderUpdate — unresolved $ref
  - `place_of_service_code_as_submitted` '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' — Box 24B on the CMS-1500 claim form. Line-level place of service is not currently supported. 02 for telemedicine, 11 for in-person. Full list here: https://www.cms.gov/Medicare/Coding/place-of-service-codes/Place_of_Service_Code_Set
  - `related_causes_information` V1RelatedCausesInformationUpdate — unresolved $ref
  - `property_casualty_claim_number` string — 837p Loop2010 REF02, CMS1500 Box 11b
  - `accident_date` string, date — 837p Loop2300 DTP*439, CMS1500 Box 15
  - `property_casualty_patient_identifier` V1PropertyCasualtyPatientIdentifierUpdate — unresolved $ref
  - `health_care_code_information` V1HealthCareCodeInformationUpdate — unresolved $ref
  - `attending_provider` V2RenderingProviderUpdate — unresolved $ref
  - `admission_hour` integer — 837i Loop 2300 DTP-03 Extension of the admission date with hour (0-23 integer) details.
  - `admission_type_code` V1TypeOfAdmissionOrVisitCode — unresolved $ref
  - `admission_source_code` V1PointOfOriginForAdmissionOrVisitCode — unresolved $ref
  - `discharge_hour` integer — 837i Loop 2300 DTP-03 Extension of the discharge date with hour (0-23 integer) details.
  - `discharge_status` V1PatientDischargeStatusCode — unresolved $ref
  - `operating_provider` V2RenderingProviderUpdate — unresolved $ref
  - `other_operating_provider` V2RenderingProviderUpdate — unresolved $ref
  - `type_of_bill` V1TypeOfBillCompositeUpdate — unresolved $ref
  - `accident_state_or_province_code` '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'
  - `submission_expectation` V4EncounterSubmissionExpectation — unresolved $ref

## Response `200`

Response with status 200

- V4Encounter — unresolved $ref

## Other responses

- `403` — Error response with status 403
- `404` — Error response with status 404
- `422` — Error response with status 422

---

[API](https://skmtc.net/joincandidhealth/apis/api-reference.md) · [All operations](https://skmtc.net/joincandidhealth/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/joincandidhealth/api-reference/revisions/7cc5974e4128/schema)