> 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 POST https://pre-api.joincandidhealth.com/appointments/v1 Content-Type: application/json Adds an appointment. VersionConflictError is returned when the placer_appointment_id is already in use. Reference: https://docs.joincandidhealth.com/api-reference/pre-encounter/appointments/v-1/create ## 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 ### 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 ### 409 Version Conflict Error - `errorName` ("VersionConflictError", required) - `content` (VersionConflictErrorBody, required) ### 404 Not Found Error - `errorName` ("NotFoundError", required) - `content` (ErrorBase4xx, 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) ### VersionConflictErrorBody - `message` (string, required) - `data` (any, optional) - `latest_version` (integer, optional) ### ErrorBase4xx - `message` (string, required) - `data` (any, 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" payload = { "patient_id": "patient_id", "start_timestamp": "2024-01-15T09:30:00Z", "service_duration": 1, "services": [{}, {}] } headers = { "Authorization": ".", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://pre-api.joincandidhealth.com/appointments/v1'; const options = { method: 'POST', 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" 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("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://pre-api.joincandidhealth.com/appointments/v1") 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 \"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.post("https://pre-api.joincandidhealth.com/appointments/v1") .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('POST', 'https://pre-api.joincandidhealth.com/appointments/v1', [ '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"); var request = new RestRequest(Method.POST); 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")! 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() ```