For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Contact Sales
DocsAPI reference
DocsAPI reference
  • API Reference
          • POSTCreate
          • GETGet Visits
          • GETGet
          • GETGet History
          • PUTUpdate
          • GETScan
          • DELDeactivate
Contact Sales
LogoLogo
API ReferencePre EncounterAppointmentsV1

Update

Beta
PUT
/appointments/v1/:id/:version
PUT
/appointments/v1/:id/:version
$curl -X PUT https://pre-api.joincandidhealth.com/appointments/v1/id/version \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "patient_id": "patient_id",
>  "start_timestamp": "2024-01-15T09:30:00Z",
>  "service_duration": 1,
>  "services": [
>    {},
>    {}
>  ]
>}'
1{
2  "deactivated": true,
3  "id": "id",
4  "organization_id": "organization_id",
5  "patient_id": "patient_id",
6  "service_duration": 1,
7  "services": [
8    {
9      "universal_service_identifier": "MD_Visit",
10      "start_timestamp": "2024-01-15T09:30:00Z"
11    },
12    {
13      "universal_service_identifier": "MD_Visit",
14      "start_timestamp": "2024-01-15T09:30:00Z"
15    }
16  ],
17  "start_timestamp": "2024-01-15T09:30:00Z",
18  "updated_at": "2024-01-15T09:30:00Z",
19  "updating_user_id": "updating_user_id",
20  "version": 1,
21  "appointment_details": "appointment_details",
22  "attending_doctor": {
23    "name": {
24      "family": "family",
25      "given": [
26        "given",
27        "given"
28      ],
29      "use": "USUAL",
30      "period": {
31        "start": "2023-01-15",
32        "end": "2023-01-15"
33      },
34      "suffix": "suffix"
35    },
36    "telecoms": [
37      {
38        "value": "value",
39        "use": "HOME",
40        "period": {
41          "start": "2023-01-15",
42          "end": "2023-01-15"
43        }
44      },
45      {
46        "value": "value",
47        "use": "HOME",
48        "period": {
49          "start": "2023-01-15",
50          "end": "2023-01-15"
51        }
52      }
53    ],
54    "type": "PRIMARY",
55    "npi": "npi",
56    "addresses": [
57      {
58        "use": "HOME",
59        "line": [
60          "line",
61          "line"
62        ],
63        "city": "city",
64        "state": "state",
65        "postal_code": "postal_code",
66        "country": "country",
67        "county": "county",
68        "period": {
69          "start": "2023-01-15",
70          "end": "2023-01-15"
71        }
72      },
73      {
74        "use": "HOME",
75        "line": [
76          "line",
77          "line"
78        ],
79        "city": "city",
80        "state": "state",
81        "postal_code": "postal_code",
82        "country": "country",
83        "county": "county",
84        "period": {
85          "start": "2023-01-15",
86          "end": "2023-01-15"
87        }
88      }
89    ],
90    "period": {
91      "start": "2023-01-15",
92      "end": "2023-01-15"
93    },
94    "canonical_id": "canonical_id",
95    "fax": "fax",
96    "service_facilities": [
97      {
98        "service_facility_id": "service_facility_id"
99      },
100      {
101        "service_facility_id": "service_facility_id"
102      }
103    ]
104  },
105  "automated_eligibility_check_complete": true,
106  "checked_in_timestamp": "2024-01-15T09:30:00Z",
107  "estimated_copay_cents": 1,
108  "estimated_patient_responsibility_cents": 1,
109  "location_resource_id": "location_resource_id",
110  "not_ready_reason": "INACTIVE_PRIMARY",
111  "notes": "notes",
112  "patient_deposit_cents": 1,
113  "placer_appointment_id": "placer_appointment_id",
114  "status": "PENDING",
115  "work_queue": "EMERGENT_ISSUE"
116}

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.

Was this page helpful?
Previous

Scan

Next
Built with

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Path parameters

idstringRequired
The unique identifier for an Appointment.
versionstringRequired

Request

This endpoint expects an object.
patient_idstringRequired

The Candid-defined patient identifier.

start_timestampdatetimeRequired
service_durationintegerRequired
The requested length of time allotted for the appointment. The units are in minutes.
serviceslist of objectsRequired
statusenumOptional

Defaults to PENDING. If status is NOT_READY, work_queue must be set. If status is READY or CHECKED_IN, work_queue must be null. If status is CHECKED_IN, checked_in_timestamp must be set. If checked_in_timestamp is set, status must be CHECKED_IN.

Allowed values:
not_ready_reasonenumOptional

The reason the appointment is NOT_READY. Must only be set when status is NOT_READY; it is cleared otherwise. MANUAL is the only value that may be set via the API.

placer_appointment_idstringOptional

ID for the appointment/order for the event.

attending_doctorobjectOptional
Attending physician information. The attending physician will be stored as the Current MD for the patient.
estimated_copay_centsintegerOptional
estimated_patient_responsibility_centsintegerOptional
patient_deposit_centsintegerOptional
appointment_detailsstringOptional
checked_in_timestampdatetimeOptional

The timestamp when the patient checked in for their appointment. If status is CHECKED_IN, checked_in_timestamp must be set. If checked_in_timestamp is set, status must be CHECKED_IN.

notesstringOptional
location_resource_idstringOptional

Contains the coded identification of the location being scheduled. Components: <Identifier (ST)>^<Text (ST)>

automated_eligibility_check_completebooleanOptional
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_queueenumOptional

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, work_queue must be null.

Allowed values:

Response

This endpoint returns an object.
deactivatedboolean
True if the object is deactivated. Deactivated objects are not returned in search results but are returned in all other endpoints including scan.
idstring
The unique identifier for an Appointment.
organization_idstring
The organization that owns this object.
patient_idstring

The Candid-defined patient identifier.

service_durationinteger
The requested length of time allotted for the appointment. The units are in minutes.
serviceslist of objects
start_timestampdatetime
updated_atdatetime
updating_user_idstring
The user ID of the user who last updated the object.
versioninteger
The version of the object. Any update to any property of an object object will create a new version.
appointment_detailsstring
attending_doctorobject
Attending physician information. The attending physician will be stored as the Current MD for the patient.
automated_eligibility_check_completeboolean
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.
checked_in_timestampdatetime

The timestamp when the patient checked in for their appointment. If status is CHECKED_IN, checked_in_timestamp must be set. If checked_in_timestamp is set, status must be CHECKED_IN.

estimated_copay_centsinteger
estimated_patient_responsibility_centsinteger
location_resource_idstring

Contains the coded identification of the location being scheduled. Components: <Identifier (ST)>^<Text (ST)>

not_ready_reasonenum

The reason the appointment is NOT_READY. Must only be set when status is NOT_READY; it is cleared otherwise. MANUAL is the only value that may be set via the API.

notesstring
patient_deposit_centsinteger
placer_appointment_idstring

ID for the appointment/order for the event.

statusenum

Defaults to PENDING. If status is NOT_READY, work_queue must be set. If status is READY or CHECKED_IN, work_queue must be null. If status is CHECKED_IN, checked_in_timestamp must be set. If checked_in_timestamp is set, status must be CHECKED_IN.

Allowed values:
work_queueenum

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, work_queue must be null.

Allowed values:

Errors

404
Not Found Error
409
Version Conflict Error