> 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. # Update PUT https://pre-api.joincandidhealth.com/appointments/v1/{id}/{version} Content-Type: application/json Updates an appointment. The path must contain the next version number to prevent race conditions. For example, if the current version of the appointment is n, you will need to send a request to this endpoint with `/{id}/n+1` to update the appointment. Updating historic versions is not supported. Reference: https://docs.joincandidhealth.com/api-reference/pre-encounter/appointments/v-1/update ## Authentication - OAuth2 — send the obtained token as `Authorization: Bearer ` ## Servers - `https://pre-api.joincandidhealth.com` (Production, default) - `https://pre-api-staging.joincandidhealth.com` (Staging) - `https://sandbox-pre-api.joincandidhealth.com` (CandidSandbox) - `https://staging-pre-api.joincandidhealth.com` (CandidStaging) - `http://localhost:4000` (Local) ## Request ### Path parameters - `id` (string, required) — The unique identifier for an Appointment. - `version` (string, required) ### Body (application/json) This endpoint expects a MutableAppointment. - `patient_id` (string, required) — The Candid-defined patient identifier. - `start_timestamp` (datetime, required) - `service_duration` (integer, required) — The requested length of time allotted for the appointment. The units are in minutes. - `services` (list of Service, required) - `status` (enum, optional) — Defaults to PENDING. If status is NOT_READY, work_queue must be set. If status is READY, CHECKED_OUT, or NO_SHOW, work_queue must be null. checked_in_timestamp must be set if and only if status is CHECKED_IN or CHECKED_OUT, and checked_out_timestamp must be set if and only if status is CHECKED_OUT. - Allowed values: `PENDING`, `NOT_READY`, `READY`, `CHECKED_IN`, `CHECKED_OUT`, `NO_SHOW` - `not_ready_reason` (enum, optional) — The reason the appointment is NOT_READY. Must only be set when status is NOT_READY; it is cleared otherwise. It is not recommended to change this value manually via API. - Allowed values: `INACTIVE_PRIMARY`, `INACTIVE_SECONDARY`, `MEDICARE_ADVANTAGE_CONVERSION`, `MEDICAID_MANAGED_CONVERSION`, `UNAVAILABLE_PRIMARY`, `UNAVAILABLE_SECONDARY`, `PENDING_PRIMARY`, `PENDING_SECONDARY`, `ELIGIBILITY_CHECK_FAILED_PRIMARY`, `ELIGIBILITY_CHECK_FAILED_SECONDARY`, `NEW_COMBO`, `NEW_INSURANCE`, `PRIOR_APPOINTMENT_NOT_READY`, `NO_COVERAGE`, `ERROR`, `MANUAL` - `ready_source` (enum, optional) — The method that set the appointment status to READY. It is not recommended to change this value manually via API. Must only be set when the status is READY, CHECKED_IN, CHECKED_OUT or NO_SHOW, it is cleared otherwise. - Allowed values: `MANUAL`, `MACHINE` - `placer_appointment_id` (string, optional) — ID for the appointment/order for the event. - `placer_system_name` (string, optional) — The name of the upstream system that placed this appointment. - `attending_doctor` (ExternalProvider, optional) — Attending physician information. The attending physician will be stored as the Current MD for the patient. - `estimated_copay_cents` (integer, optional) - `estimated_patient_responsibility_cents` (integer, optional) — The estimated amount the patient will be responsible for paying at the time of service. This does not include the copay. - `patient_deposit_cents` (integer, optional) - `appointment_details` (string, optional) - `checked_in_timestamp` (datetime, optional) — The timestamp when the patient checked in for their appointment. Must be set when status is CHECKED_IN or CHECKED_OUT, and must be unset otherwise. - `checked_out_timestamp` (datetime, optional) — The timestamp when the patient checked out of their appointment. Must be set when status is CHECKED_OUT, and must be unset otherwise. - `appointment_reason_detail` (AppointmentReasonDetail, optional) — The clinical context for the appointment. - `medical_necessity_verified` (boolean, optional) — True if medical necessity for this appointment has been verified. - `prior_authorization_status` (enum, optional) — The prior authorization status for this appointment. - Allowed values: `NOT_REQUIRED`, `REQUIRED`, `PENDING`, `APPROVED`, `PARTIALLY_APPROVED`, `DENIED`, `EXPIRED` - `notes` (string, optional) - `location_resource_id` (string, optional) — Contains the coded identification of the location being scheduled. Components: \^\ - `automated_eligibility_check_complete` (boolean, optional) — True if the automated eligibility check has been completed. It is not recommended to change this value manually via API. This refers explicitly to the automated eligibility check that occurs a specific number of days before the appointment. - `work_queue` (enum, optional) — The work queue that the appointment belongs to. It is not recommended to change this value manually via API. If status is NOT_READY, work_queue must be set. If status is READY, CHECKED_OUT or NO_SHOW, work_queue must be null. - Allowed values: `EMERGENT_ISSUE`, `NEW_PATIENT`, `RETURNING_PATIENT`, `MANUAL_ESCALATION` - `cancellation_reason` (string, optional) — The reason the appointment was cancelled. This value cannot be set on create or update; it is only set by the deactivate endpoint, and is cleared if the appointment is reactivated. ## Response ### 200 - `deactivated` (boolean, required) — True if the object is deactivated. Deactivated objects are not returned in search results but are returned in all other endpoints including scan. - `id` (string, required) — The unique identifier for an Appointment. - `organization_id` (string, required) — The organization that owns this object. - `patient_id` (string, required) — The Candid-defined patient identifier. - `service_duration` (integer, required) — The requested length of time allotted for the appointment. The units are in minutes. - `services` (list of Service, required) - `start_timestamp` (datetime, required) - `updated_at` (datetime, required) - `updating_user_id` (string, required) — The user ID of the user who last updated the object. - `version` (integer, required) — The version of the object. Any update to any property of an object object will create a new version. - `appointment_details` (string, optional) - `appointment_reason_detail` (AppointmentReasonDetail, optional) — The clinical context for the appointment. - `attending_doctor` (ExternalProvider, optional) — Attending physician information. The attending physician will be stored as the Current MD for the patient. - `automated_eligibility_check_complete` (boolean, optional) — True if the automated eligibility check has been completed. It is not recommended to change this value manually via API. This refers explicitly to the automated eligibility check that occurs a specific number of days before the appointment. - `cancellation_reason` (string, optional) — The reason the appointment was cancelled. This value cannot be set on create or update; it is only set by the deactivate endpoint, and is cleared if the appointment is reactivated. - `checked_in_timestamp` (datetime, optional) — The timestamp when the patient checked in for their appointment. Must be set when status is CHECKED_IN or CHECKED_OUT, and must be unset otherwise. - `checked_out_timestamp` (datetime, optional) — The timestamp when the patient checked out of their appointment. Must be set when status is CHECKED_OUT, and must be unset otherwise. - `estimated_copay_cents` (integer, optional) - `estimated_patient_responsibility_cents` (integer, optional) — The estimated amount the patient will be responsible for paying at the time of service. This does not include the copay. - `location_resource_id` (string, optional) — Contains the coded identification of the location being scheduled. Components: \^\ - `medical_necessity_verified` (boolean, optional) — True if medical necessity for this appointment has been verified. - `not_ready_reason` (enum, optional) — The reason the appointment is NOT_READY. Must only be set when status is NOT_READY; it is cleared otherwise. It is not recommended to change this value manually via API. - Allowed values: `INACTIVE_PRIMARY`, `INACTIVE_SECONDARY`, `MEDICARE_ADVANTAGE_CONVERSION`, `MEDICAID_MANAGED_CONVERSION`, `UNAVAILABLE_PRIMARY`, `UNAVAILABLE_SECONDARY`, `PENDING_PRIMARY`, `PENDING_SECONDARY`, `ELIGIBILITY_CHECK_FAILED_PRIMARY`, `ELIGIBILITY_CHECK_FAILED_SECONDARY`, `NEW_COMBO`, `NEW_INSURANCE`, `PRIOR_APPOINTMENT_NOT_READY`, `NO_COVERAGE`, `ERROR`, `MANUAL` - `notes` (string, optional) - `patient_deposit_cents` (integer, optional) - `placer_appointment_id` (string, optional) — ID for the appointment/order for the event. - `placer_system_name` (string, optional) — The name of the upstream system that placed this appointment. - `prior_authorization_status` (enum, optional) — The prior authorization status for this appointment. - Allowed values: `NOT_REQUIRED`, `REQUIRED`, `PENDING`, `APPROVED`, `PARTIALLY_APPROVED`, `DENIED`, `EXPIRED` - `ready_source` (enum, optional) — The method that set the appointment status to READY. It is not recommended to change this value manually via API. Must only be set when the status is READY, CHECKED_IN, CHECKED_OUT or NO_SHOW, it is cleared otherwise. - Allowed values: `MANUAL`, `MACHINE` - `status` (enum, optional) — Defaults to PENDING. If status is NOT_READY, work_queue must be set. If status is READY, CHECKED_OUT, or NO_SHOW, work_queue must be null. checked_in_timestamp must be set if and only if status is CHECKED_IN or CHECKED_OUT, and checked_out_timestamp must be set if and only if status is CHECKED_OUT. - Allowed values: `PENDING`, `NOT_READY`, `READY`, `CHECKED_IN`, `CHECKED_OUT`, `NO_SHOW` - `work_queue` (enum, optional) — The work queue that the appointment belongs to. It is not recommended to change this value manually via API. If status is NOT_READY, work_queue must be set. If status is READY, CHECKED_OUT or NO_SHOW, work_queue must be null. - Allowed values: `EMERGENT_ISSUE`, `NEW_PATIENT`, `RETURNING_PATIENT`, `MANUAL_ESCALATION` ## Errors ### 404 Not Found Error - `errorName` ("NotFoundError", required) - `content` (ErrorBase4xx, required) ### 409 Version Conflict Error - `errorName` ("VersionConflictError", required) - `content` (VersionConflictErrorBody, required) ## Types ### Service - `universal_service_identifier` (enum, optional) — Contains the code describing the activity type that is being scheduled. - Allowed values: `MD_Visit`, `Treatment`, `Tests`, `Activity` - `start_timestamp` (datetime, optional) ### ExternalProvider - `name` (HumanName, required) - `telecoms` (list of ContactPoint, required) - `type` (enum, optional) — Defaults to ATTENDING. - Allowed values: `PRIMARY`, `REFERRING`, `ATTENDING` - `npi` (string, optional) - `addresses` (list of Address, optional) - `period` (Period, optional) - `canonical_id` (string, optional) — The unique identifier for a provider configured in the Candid system - `fax` (string, optional) - `other_fax_numbers` (list of string, optional) - `emails` (list of string, optional) - `service_facilities` (list of PatientServiceFacility, optional) — Associated service facilities for this provider. ### AppointmentReasonDetail The clinical context for the appointment. - `diagnosis_codes` (list of string, optional) - `procedure_codes` (list of string, optional) ### ErrorBase4xx - `message` (string, required) - `data` (any, optional) ### VersionConflictErrorBody - `message` (string, required) - `data` (any, optional) - `latest_version` (integer, optional) ### HumanName - `family` (string, required) - `given` (list of string, required) - `use` (enum, required) - Allowed values: `USUAL`, `OFFICIAL`, `TEMP`, `NICKNAME`, `ANONYMOUS`, `OLD`, `MAIDEN` - `period` (Period, optional) - `suffix` (string, optional) ### ContactPoint - `value` (string, required) - `use` (enum, required) - Allowed values: `HOME`, `WORK`, `TEMP`, `OLD`, `MOBILE` - `period` (Period, optional) ### Address - `use` (enum, required) - Allowed values: `HOME`, `WORK`, `TEMP`, `OLD`, `BILLING` - `line` (list of string, required) - `city` (string, required) - `state` (string, required) - `postal_code` (string, required) - `country` (string, required) - `administrative_area` (string, optional) — The top-level administrative subdivision of the country for addresses outside the US — for example a Canadian province, a UK county, or a Japanese prefecture. Only permitted on international addresses: `country` must be present and non-US, and `state` must be "FC" (the X12 foreign-country sentinel). For US addresses use `state` instead. - `county` (string, optional) - `period` (Period, optional) ### Period - `start` (date, optional) - `end` (date, optional) ### PatientServiceFacility Represents a canonical service facility attached to a patient or patient dependent object - `service_facility_id` (string, required) — The unique identifier for a service facility configured in the Candid system ## Examples **Request** ```json { "patient_id": "patient_id", "start_timestamp": "2024-01-15T09:30:00Z", "service_duration": 1, "services": [ {}, {} ] } ``` **Response** ```json { "deactivated": true, "id": "id", "organization_id": "organization_id", "patient_id": "patient_id", "service_duration": 1, "services": [ { "universal_service_identifier": "MD_Visit", "start_timestamp": "2024-01-15T09:30:00Z" }, { "universal_service_identifier": "MD_Visit", "start_timestamp": "2024-01-15T09:30:00Z" } ], "start_timestamp": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "updating_user_id": "updating_user_id", "version": 1, "appointment_details": "appointment_details", "appointment_reason_detail": { "diagnosis_codes": [ "diagnosis_codes", "diagnosis_codes" ], "procedure_codes": [ "procedure_codes", "procedure_codes" ] }, "attending_doctor": { "name": { "family": "family", "given": [ "given", "given" ], "use": "USUAL", "period": { "start": "2023-01-15", "end": "2023-01-15" }, "suffix": "suffix" }, "telecoms": [ { "value": "value", "use": "HOME", "period": { "start": "2023-01-15", "end": "2023-01-15" } }, { "value": "value", "use": "HOME", "period": { "start": "2023-01-15", "end": "2023-01-15" } } ], "type": "PRIMARY", "npi": "npi", "addresses": [ { "use": "HOME", "line": [ "line", "line" ], "city": "city", "state": "state", "postal_code": "postal_code", "country": "country", "administrative_area": "administrative_area", "county": "county", "period": { "start": "2023-01-15", "end": "2023-01-15" } }, { "use": "HOME", "line": [ "line", "line" ], "city": "city", "state": "state", "postal_code": "postal_code", "country": "country", "administrative_area": "administrative_area", "county": "county", "period": { "start": "2023-01-15", "end": "2023-01-15" } } ], "period": { "start": "2023-01-15", "end": "2023-01-15" }, "canonical_id": "canonical_id", "fax": "fax", "other_fax_numbers": [ "other_fax_numbers", "other_fax_numbers" ], "emails": [ "emails", "emails" ], "service_facilities": [ { "service_facility_id": "service_facility_id" }, { "service_facility_id": "service_facility_id" } ] }, "automated_eligibility_check_complete": true, "cancellation_reason": "cancellation_reason", "checked_in_timestamp": "2024-01-15T09:30:00Z", "checked_out_timestamp": "2024-01-15T09:30:00Z", "estimated_copay_cents": 1, "estimated_patient_responsibility_cents": 1, "location_resource_id": "location_resource_id", "medical_necessity_verified": true, "not_ready_reason": "INACTIVE_PRIMARY", "notes": "notes", "patient_deposit_cents": 1, "placer_appointment_id": "placer_appointment_id", "placer_system_name": "placer_system_name", "prior_authorization_status": "NOT_REQUIRED", "ready_source": "MANUAL", "status": "PENDING", "work_queue": "EMERGENT_ISSUE" } ``` **SDK Code** ```python import requests url = "https://pre-api.joincandidhealth.com/appointments/v1/id/version" payload = { "patient_id": "patient_id", "start_timestamp": "2024-01-15T09:30:00Z", "service_duration": 1, "services": [{}, {}] } headers = { "Authorization": ".", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://pre-api.joincandidhealth.com/appointments/v1/id/version'; const options = { method: 'PUT', headers: {Authorization: '.', 'Content-Type': 'application/json'}, body: '{"patient_id":"patient_id","start_timestamp":"2024-01-15T09:30:00Z","service_duration":1,"services":[{},{}]}' }; 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://pre-api.joincandidhealth.com/appointments/v1/id/version" payload := strings.NewReader("{\n \"patient_id\": \"patient_id\",\n \"start_timestamp\": \"2024-01-15T09:30:00Z\",\n \"service_duration\": 1,\n \"services\": [\n {},\n {}\n ]\n}") req, _ := http.NewRequest("PUT", 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://pre-api.joincandidhealth.com/appointments/v1/id/version") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Authorization"] = '.' request["Content-Type"] = 'application/json' request.body = "{\n \"patient_id\": \"patient_id\",\n \"start_timestamp\": \"2024-01-15T09:30:00Z\",\n \"service_duration\": 1,\n \"services\": [\n {},\n {}\n ]\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.put("https://pre-api.joincandidhealth.com/appointments/v1/id/version") .header("Authorization", ".") .header("Content-Type", "application/json") .body("{\n \"patient_id\": \"patient_id\",\n \"start_timestamp\": \"2024-01-15T09:30:00Z\",\n \"service_duration\": 1,\n \"services\": [\n {},\n {}\n ]\n}") .asString(); ``` ```php request('PUT', 'https://pre-api.joincandidhealth.com/appointments/v1/id/version', [ 'body' => '{ "patient_id": "patient_id", "start_timestamp": "2024-01-15T09:30:00Z", "service_duration": 1, "services": [ {}, {} ] }', 'headers' => [ 'Authorization' => '.', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://pre-api.joincandidhealth.com/appointments/v1/id/version"); var request = new RestRequest(Method.PUT); request.AddHeader("Authorization", "."); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"patient_id\": \"patient_id\",\n \"start_timestamp\": \"2024-01-15T09:30:00Z\",\n \"service_duration\": 1,\n \"services\": [\n {},\n {}\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": ".", "Content-Type": "application/json" ] let parameters = [ "patient_id": "patient_id", "start_timestamp": "2024-01-15T09:30:00Z", "service_duration": 1, "services": [[], []] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://pre-api.joincandidhealth.com/appointments/v1/id/version")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" 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() ```