Update appointment via API

Hi ​@jmalfait  👋

So, the API does allow patient_id in the Edit Appointment payload per the docs, but current behaviour is that you can’t change the patient on an existing appointment. Basically the server responds with patient_id: "can not change patients". This matches what you’re seeing. I’ll flag this to our API team so the docs make this clearer.

One potential workaround would be to  create a new appointment for the correct patient, then cancel the original one with a reason (e.g. “Booked in error”). On the state mismatch: your GET shows state: "Pending", but the update error says Confirmed. That could mean the appointment changed between your read and write (e.g. auto-confirmation via SMS/Portal or another user), or the GET and PATCH hit different environments. Please try a fresh GET immediately before the PATCH, and confirm you’re using the same appointment_id and environment (sandbox vs live). 

If you require further help, feel free to reach out to our partnership team! 

Thank for the feedback ​@Saymon 

We will try the cancel/delete and create approach.

The state mismatch is strange. We are using the same appointment_id and environment.
When getting the appointment we see the following.

{
  "appointment": {
    "id": 757579675,
    "patient_id": 1013,
    "state": "Pending",
    "uuid": "887372ca-aca1-418c-a952-82d152e5cf3a"
  }
}

When we try setting the state and patient_id in one go using.

PUT {{baseUrl}}/{{apiVersion}}/appointments/757579675
Authorization: Bearer {{apiToken}}
User-Agent: {{userAgent}}
Content-Type: application/json

{
  "appointment": {
    "state": "Confirmed",
    "patient_id": 1014
  }
}

This produces the following HTTP 422 response

{
  "error": {
    "type": "invalid_request_error",
    "message": "The appointment could not be processed",
    "params": {
      "state": [
        "The appointment can not be updated as the current status is: Confirmed"
      ],
      "patient_id": [
        "can not change patients"
      ]
    }
  }
}

Hi ​@jmalfait 

Thanks for the details. 

I have’t personally seen this before, so I’ll have to check with our API team. However, my feeling is that the state change is happening somewhere else in between, possibly via the Portal, SMS confirmations, or even another user’s action, so the record validation fails when you try to update both fields at once.

Creating a new appointment for the right patient and then linking or tagging it back to the original one using metadata or notes could work, rather than fully deleting or losing the history. It keeps everything traceable and clean in both systems.

You could also try sending just the state change on its own, right after a fresh GET, to see if that clears the “Confirmed” validation message, that would at least confirm whether the timing is the culprit.

Hi ​@jmalfait ,
I checked with our API team and here’s the expected behaviour:

• You can add a patient to an appointment only if it doesn’t have one yet. Once a patient is set, the API won’t let you change or remove it.

• After an appointment is Confirmed, only the state and notes can be edited.

That’s why your call with both state and patient_id returns the 422: the platform blocks changing the patient on an existing (and especially Confirmed) appointment.

If you need to move the slot to another patient, create a new appointment for the correct patient at the same time/provider, then cancel the original (e.g. reason “Booked in error”). If you want to keep the audit trail tidy, you can add a small note or metadata on both to link them. Hope this helps!