API Name: put-appointment


This API creates or updates an Appointment record representing a scheduled healthcare encounter for a patient. The appointment includes details such as the attending practitioners, location, reason, and referral information.

Specification


Endpoint [baseurl]/Appointment/$put-appointment
Protocol HTTPS
HTTP Method Post
HTTP Header Content-Type: application/fhir+json

Request Body

Remarks:

  • This is a type-level operation that operates on the Appointment resource type.
  • The request body contains a single Appointment resource with contained Practitioner, Organization, Location, and ServiceRequest resources.
  • (All Slices) is an automatically generated section and should be ignored. Do not pass this as an input parameter. It will also not be part of response.

Appointment

idΣ0..1id
metaΣ0..1Meta
implicitRulesΣ ?!0..1uri
language0..1codeBinding
textC0..1Narrative
OrganizationC0..1Organization
PractitionerC0..*Practitioner
LocationC0..*Location
ServiceRequestC0..1ServiceRequest
extensionC0..*Extension
modifierExtensionΣ ?! C0..*Extension
id0..0string
extensionC0..0Extension
useΣ ?!0..0codeBinding
typeΣ0..0CodeableConceptBinding
systemΣ1..1uriFixed Value
valueΣ C1..1string
periodΣ C0..0Period
assignerΣ C0..0Reference(Organization)
id0..0string
extensionC0..0Extension
useΣ ?!0..0codeBinding
typeΣ0..0CodeableConceptBinding
systemΣ1..1uriFixed Value
valueΣ C1..1string
periodΣ C0..0Period
assignerΣ C0..0Reference(Organization)
id0..0string
extensionC0..0Extension
useΣ ?!0..0codeBinding
typeΣ0..0CodeableConceptBinding
systemΣ1..1uriFixed Value
valueΣ C1..1string
periodΣ C0..0Period
assignerΣ C0..0Reference(Organization)
id0..0string
extensionC0..0Extension
useΣ ?!0..0codeBinding
typeΣ0..0CodeableConceptBinding
systemΣ1..1uriFixed Value
valueΣ C1..1string
periodΣ C0..0Period
assignerΣ C0..0Reference(Organization)
statusΣ ?! C1..1codeBinding
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
referenceΣ C0..0Reference
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
referenceΣ C0..1Reference
priority0..0CodeableConcept
description0..0string
replacesC0..0Reference(Appointment)
virtualService0..0VirtualServiceDetail
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
previousAppointmentC0..0Reference(Appointment)
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
startΣ C1..1instant
endΣ C0..0instant
minutesDuration0..1positiveInt
requestedPeriodC0..0Period
slotC0..0Reference(Slot)
accountC0..0Reference(Account)
created0..0dateTime
cancellationDateC0..0dateTime
id0..0string
extensionC0..0Extension
timeΣ0..0dateTime
textΣ1..1markdown
patientInstruction0..0CodeableReference(Binary | Communication | DocumentReference)
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
id0..0string
extensionC0..0Extension
modifierExtensionΣ ?! C0..0Extension
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
periodC0..0Period
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
requiredΣ0..0boolean
statusΣ1..1codeBinding
recurrenceId0..0positiveInt
occurrenceChanged0..0boolean
{
"resourceType": "Appointment",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-appointment"
]
},
{
"resourceType": "Organization",
"id": "org-001",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-organization"
]
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/hci-code",
"value": "11234"
}
],
"active": true,
"type": [
{
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/organization-type",
"code": "hospital",
"display": "Hospital"
}
]
}
],
"name": "National University Hospital"
},
{
"resourceType": "Practitioner",
"id": "pract-001",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-practitioner"
]
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/mcr",
"value": "M12345"
}
],
"name": [
{
"text": "Dr. Sarah Lim"
}
]
},
{
"resourceType": "Practitioner",
"id": "pract-002",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-practitioner"
]
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/mcr",
"value": "M67890"
}
],
"name": [
{
"text": "Dr. Michael Tan"
}
]
},
{
"resourceType": "Location",
"id": "loc-001",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-location"
]
},
"name": "Cardiology Clinic Room 1",
"type": [
{
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/location-type",
"code": "clinic",
"display": "Clinic"
}
]
}
],
"type": "Organization",
"system": "https://fhir.synapxe.sg/NamingSystem/hci-code",
"value": "11234"
}
}
},
{
"resourceType": "ServiceRequest",
"id": "sr-001",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-servicerequest"
]
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/order-no",
"value": "ORD-2026-001234"
}
],
"status": "active",
"intent": "order",
"subject": {
"type": "Patient",
"system": "https://fhir.synapxe.sg/NamingSystem/nric",
"value": "S1234567A"
}
},
"authoredOn": "2026-02-08T09:00:00+08:00",
"type": "Practitioner",
"system": "https://fhir.synapxe.sg/NamingSystem/mcr",
"value": "M12345"
},
"display": "Dr. Sarah Lim"
}
}
],
{
"system": "https://fhir.synapxe.sg/NamingSystem/record-id",
"value": "REC-APT-2026-001234"
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/appointment-id",
"value": "APT-2026-001234"
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/group-no",
"value": "GRP-APT-001"
}
],
"status": "booked",
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/reasonforcancellation",
"code": "PATI",
"display": "Patient Initiated"
}
]
},
{
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/patient-type",
"code": "O",
"display": "Outpatient visit"
}
]
}
],
{
"concept": {
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/appointment-type",
"code": "CON",
"display": "Consultation, Nursing"
}
]
}
}
],
{
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/department-specialty",
"code": "PGN",
"display": "Paediatric Genetics"
}
]
}
],
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/movement-type",
"code": "DS",
"display": "Day Surgery"
}
]
},
"reason": [
{
"concept": {
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/reason-for-appointment",
"code": "1",
"display": "A&E"
}
]
}
}
],
{
"reference": "#loc-001",
"display": "Cardiology Clinic Room 1"
}
],
"type": "Appointment",
"system": "https://fhir.synapxe.sg/NamingSystem/appointment-id",
"value": "APT-2026-000999"
}
},
"start": "2026-02-15T10:00:00+08:00",
"note": [
{
"text": "Patient requires wheelchair assistance upon arrival. Follow-up appointment for post-operative cardiology review."
}
],
"basedOn": [
{
"reference": "#sr-001"
}
],
"subject": {
"type": "Patient",
"system": "https://fhir.synapxe.sg/NamingSystem/nric",
"value": "S1234567A"
},
"display": "John Tan"
},
{
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "ATND",
"display": "Attender"
}
]
}
],
"actor": {
"reference": "#pract-001",
"display": "Dr. Sarah Lim"
},
"status": "accepted"
},
{
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "CON",
"display": "Consultant"
}
]
}
],
"actor": {
"reference": "#pract-002",
"display": "Dr. Michael Tan"
},
"status": "accepted"
},
{
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "LOC",
"display": "Location"
}
]
}
],
"actor": {
"reference": "#org-001",
"display": "National University Hospital"
},
"status": "accepted"
}
]
}

Successful Response

idΣ0..1id
metaΣ0..1Meta
implicitRulesΣ ?!0..1uri
language0..1codeBinding
textC0..1Narrative
OrganizationC0..1Organization
PractitionerC0..*Practitioner
LocationC0..*Location
ServiceRequestC0..1ServiceRequest
extensionC0..*Extension
modifierExtensionΣ ?! C0..*Extension
id0..0string
extensionC0..0Extension
useΣ ?!0..0codeBinding
typeΣ0..0CodeableConceptBinding
systemΣ1..1uriFixed Value
valueΣ C1..1string
periodΣ C0..0Period
assignerΣ C0..0Reference(Organization)
id0..0string
extensionC0..0Extension
useΣ ?!0..0codeBinding
typeΣ0..0CodeableConceptBinding
systemΣ1..1uriFixed Value
valueΣ C1..1string
periodΣ C0..0Period
assignerΣ C0..0Reference(Organization)
id0..0string
extensionC0..0Extension
useΣ ?!0..0codeBinding
typeΣ0..0CodeableConceptBinding
systemΣ1..1uriFixed Value
valueΣ C1..1string
periodΣ C0..0Period
assignerΣ C0..0Reference(Organization)
id0..0string
extensionC0..0Extension
useΣ ?!0..0codeBinding
typeΣ0..0CodeableConceptBinding
systemΣ1..1uriFixed Value
valueΣ C1..1string
periodΣ C0..0Period
assignerΣ C0..0Reference(Organization)
statusΣ ?! C1..1codeBinding
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
referenceΣ C0..0Reference
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
referenceΣ C0..1Reference
priority0..0CodeableConcept
description0..0string
replacesC0..0Reference(Appointment)
virtualService0..0VirtualServiceDetail
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
previousAppointmentC0..0Reference(Appointment)
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
startΣ C1..1instant
endΣ C0..0instant
minutesDuration0..1positiveInt
requestedPeriodC0..0Period
slotC0..0Reference(Slot)
accountC0..0Reference(Account)
created0..0dateTime
cancellationDateC0..0dateTime
id0..0string
extensionC0..0Extension
timeΣ0..0dateTime
textΣ1..1markdown
patientInstruction0..0CodeableReference(Binary | Communication | DocumentReference)
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
id0..0string
extensionC0..0Extension
modifierExtensionΣ ?! C0..0Extension
id0..0string
extensionC0..0Extension
id0..0string
extensionC0..0Extension
systemΣ1..1uriFixed Value
versionΣ0..1string
codeΣ C1..1code
displayΣ C1..1string
userSelectedΣ0..0boolean
textΣ0..0string
periodC0..0Period
id0..0string
extensionC0..0Extension
referenceΣ C0..1string
typeΣ0..1uriBinding
identifierΣ C0..1Identifier
displayΣ C0..1string
requiredΣ0..0boolean
statusΣ1..1codeBinding
recurrenceId0..0positiveInt
occurrenceChanged0..0boolean
{
"resourceType": "Appointment",
"id": "apt-2026-001234",
"meta": {
"versionId": "1",
"lastUpdated": "2026-02-10T10:30:00.1+08:00",
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-appointment"
]
},
{
"resourceType": "Organization",
"id": "org-001",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-organization"
]
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/hci-code",
"value": "11234"
}
],
"active": true,
"type": [
{
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/organization-type",
"code": "hospital",
"display": "Hospital"
}
]
}
],
"name": "National University Hospital"
},
{
"resourceType": "Practitioner",
"id": "pract-001",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-practitioner"
]
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/mcr",
"value": "M12345"
}
],
"name": [
{
"text": "Dr. Sarah Lim"
}
]
},
{
"resourceType": "Practitioner",
"id": "pract-002",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-practitioner"
]
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/mcr",
"value": "M67890"
}
],
"name": [
{
"text": "Dr. Michael Tan"
}
]
},
{
"resourceType": "Location",
"id": "loc-001",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-location"
]
},
"name": "Cardiology Clinic Room 1",
"type": [
{
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/location-type",
"code": "clinic",
"display": "Clinic"
}
]
}
],
"type": "Organization",
"system": "https://fhir.synapxe.sg/NamingSystem/hci-code",
"value": "11234"
}
}
},
{
"resourceType": "ServiceRequest",
"id": "sr-001",
"meta": {
"profile": [
"https://fhir.synapxe.sg/StructureDefinition/profile-servicerequest"
]
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/order-no",
"value": "ORD-2026-001234"
}
],
"status": "active",
"intent": "order",
"subject": {
"type": "Patient",
"system": "https://fhir.synapxe.sg/NamingSystem/nric",
"value": "S1234567A"
}
},
"authoredOn": "2026-02-08T09:00:00+08:00",
"type": "Practitioner",
"system": "https://fhir.synapxe.sg/NamingSystem/mcr",
"value": "M12345"
},
"display": "Dr. Sarah Lim"
}
}
],
{
"system": "https://fhir.synapxe.sg/NamingSystem/record-id",
"value": "REC-APT-2026-001234"
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/appointment-id",
"value": "APT-2026-001234"
},
{
"system": "https://fhir.synapxe.sg/NamingSystem/group-no",
"value": "GRP-APT-001"
}
],
"status": "booked",
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/reasonforcancellation",
"code": "PATI",
"display": "Patient Initiated"
}
]
},
{
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/patient-type",
"code": "O",
"display": "Outpatient visit"
}
]
}
],
{
"concept": {
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/appointment-type",
"code": "CON",
"display": "Consultation, Nursing"
}
]
}
}
],
{
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/department-specialty",
"code": "PGN",
"display": "Paediatric Genetics"
}
]
}
],
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/movement-type",
"code": "DS",
"display": "Day Surgery"
}
]
},
"reason": [
{
"concept": {
"coding": [
{
"system": "https://fhir.synapxe.sg/CodeSystem/reason-for-appointment",
"code": "1",
"display": "A&E"
}
]
}
}
],
{
"reference": "#loc-001",
"display": "Cardiology Clinic Room 1"
}
],
"type": "Appointment",
"system": "https://fhir.synapxe.sg/NamingSystem/appointment-id",
"value": "APT-2026-000999"
}
},
"start": "2026-02-15T10:00:00+08:00",
"note": [
{
"text": "Patient requires wheelchair assistance upon arrival. Follow-up appointment for post-operative cardiology review."
}
],
"basedOn": [
{
"reference": "#sr-001"
}
],
"subject": {
"type": "Patient",
"system": "https://fhir.synapxe.sg/NamingSystem/nric",
"value": "S1234567A"
},
"display": "John Tan"
},
{
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "ATND",
"display": "Attender"
}
]
}
],
"actor": {
"reference": "#pract-001",
"display": "Dr. Sarah Lim"
},
"status": "accepted"
},
{
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "CON",
"display": "Consultant"
}
]
}
],
"actor": {
"reference": "#pract-002",
"display": "Dr. Michael Tan"
},
"status": "accepted"
},
{
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "LOC",
"display": "Location"
}
]
}
],
"actor": {
"reference": "#org-001",
"display": "National University Hospital"
},
"status": "accepted"
}
]
}

Business Level Errors


This section details the business level errors exposed by OperationOutcome resource for this operation. Refer to API Error Handling for framework level errors.

For illustration only

http status code code details.coding.code details.text
404 not-found E-10000 No matching patient found based on NRIC, Date of Birth and Gender
404 not-found E-10001 Institution code for organization is not found
404 not-found E-10002 Organization code is not found
400 business-rule E-10003 Patient is not currently enrolled to the organization
400 duplicate E-10004 An attempt was made to create a duplicate record
400 invalid E-10005 Invalid appointment identifier
400 invalid E-10006 Invalid appointment status