Skip to content
This repository was archived by the owner on Dec 20, 2024. It is now read-only.

V3 API Create or Update Appointment

Jump to bottom
jay-lee00 edited this page Jul 7, 2020 · 4 revisions

Create/Update Appointment

POST v3/admin/appointments

POST v3/patients/appointments

PUT v3/admin/appointments/{appointmentId:guid}

PUT v3/patients/appointments/{appointmentId:guid}

Creates (POST) new or updates (PUT) existing appointment.

vs/admin/... and vs/patients/... URLs are equivalent, except former are intended for use by hospital staff, while latter are for patients.

Permissions

Hospital staff should have one of the following role functions:

  • Manage_Staff_Appointments
  • Manage_Own_Appointments
  • Patient_Proxy

Manage_Own_Appointments allows to create/updated only appointments where clinician is a participant.

Patients are allowed to create/update only their own appointments and appointments of their authorized dependents.

Anyway, only appointments from user's hospital are accessible.

Body

New appointment details are sent to API as JSON object in request body.

name type description value
availabilityBlockId Guid For POST - id of the block where appointment should be created.
startTime DateTime Appointment start/end time (in current user time zone).
endTime
waiveFee bool? Is appointment chargeless? Default - false
patientQueueId Guid? Id of the patient queue record. Default - null.
appointmentTypeCode int Code of appointment type (on-demand, self-scheduled etc). Required. See enum values.
encounterTypeCode int Code of encounter type (video, phone etc.). Required. See enum values.
intakeMetadata AppointmentIntakeMetadata (object) Intake metadata Required.
PaymentRequisites AppointmentPaymentRequisitesRequest (object) Intake metadata Required.
participants AppointmentParticipantRequest[] (array of objects) Intake metadata Required.
participants AppointmentParticipantRequest[] (array of objects) Array of participants - both patients and clinicians. Required. Currently exactly two participants shold be provided - one patient and one clinician (provider).
participants[].personId Guid Id of the participant Required.
participants[].attendenceCode int Code of attendence (required, optional etc.). See enum values.
participants[].participantTypeCode int Code of participant type (patient, provider etc.). See enum values.
where string Phone number (for phone consultation) or location in free form.
serviceTypeId int Reference to service type. Required.
zonedTime ZonedTime (object) Appointment start/end time with time zone info. Optional, but if provided, takes precedence over start/end parameters above.
zonedTime.timeZoneId int Id of the timezone.
zonedTime.startTime DateTime Appointment start/end time in time zone specified above.
zonedTime.endTime

CodeSet for concerns GET api/v2/codesets?hospitalId={hospitalId}&fields=consultprimaryconcerns%2Cconsultsecondaryconcerns

Result

Result is new appointment details (AppointmentResponse) or HTTP code 400 with detailed message in the body.

Sample request

POST /api/v3/patients/appointments

{
    "availabilityBlockId": "a9799648-b068-4c71-aca1-62ae6717b999",
    "appointmentTypeCode": 3,
    "intakeMetadata": {
        "concerns": [
            {
                "isPrimary": true,
                "customCode": {
                    "code": 2305,
                    "description": "Fever (100+)"
                }
            }
        ],
        "additionalNotes": ""
    },
    "participants": [
        {
            "attendenceCode": 1,
            "personId": "53484dcc-83ea-4e9f-8af7-c93bbeb1445d",
            "participantTypeCode": 2
        },
        {
            "attendenceCode": 1,
            "personId": "5b4fd4d8-d234-40ee-bd7c-1894411c9b21",
            "participantTypeCode": 1
        }
    ],
    "encounterTypeCode": 3,
    "serviceTypeId": 307,
    "paymentRequisites": {
        "consultationAmount": 7,
        "cimProfileId": "15886118"
    },
    "startTime": "2019-03-14T17:48:00",
    "endTime": "2019-03-14T17:50:00",
    "where": "+1-34011111",
    "whereUse": 1
}

Sample response (success)

Status: 200 OK

{
    "appointmentId": "eb4c16e2-f499-4b6d-8868-d3912da23fad",
    "patientId": 25937,
    "clinicianId": 6653,
    "appointmentStatusCode": "Scheduled",
    "participants": [
        {
            "participantId": "ce2a065f-8a3a-4bf9-97de-ac931841dee3",
            "person": {
                "id": "5b4fd4d8-d234-40ee-bd7c-1894411c9b21",
                "name": {
                    "given": "Added",
                    "prefix": "",
                    "suffix": "",
                    "family": "Dependent"
                },
                "providerId": 126,
                "statusCode": 1,
                "contactTypeCode": 1,
                "phones": [
                    {
                        "id": "7dabbbc9-931b-49aa-9917-7e80998f63e8",
                        "use": "home",
                        "value": "11111"
                    },
                    {
                        "id": "f4371631-fb94-413f-bcd2-c6edb46df729",
                        "use": "mobile",
                        "value": "+1-34011111"
                    }
                ]
            },
            "status": 1,
            "attendenceCode": 1,
            "personId": "5b4fd4d8-d234-40ee-bd7c-1894411c9b21",
            "participantTypeCode": 1
        },
        {
            "participantId": "09db6995-a775-4fa0-a7fd-e98be5c5ce94",
            "person": {
                "id": "53484dcc-83ea-4e9f-8af7-c93bbeb1445d",
                "name": {
                    "given": "Bob",
                    "family": "Ivonoff"
                },
                "providerId": 126,
                "statusCode": 1,
                "contactTypeCode": 2,
                "phones": [
                    {
                        "id": "e000fcbd-7668-48fe-b30c-695ed504de6b",
                        "use": "home",
                        "value": "+37511111"
                    },
                    {
                        "id": "ecc29805-0bd0-4e15-9aaa-f03b004e176f",
                        "use": "mobile",
                        "value": "+38011111"
                    }
                ]
            },
            "status": 1,
            "attendenceCode": 1,
            "personId": "53484dcc-83ea-4e9f-8af7-c93bbeb1445d",
            "participantTypeCode": 2
        }
    ],
    "dismissed": false,
    "serviceTypeName": "Self-Scheduling",
    "availabilityBlockId": "a9799648-b068-4c71-aca1-62ae6717b999",
    "waiveFee": false,
    "startTime": "2019-03-14T17:48:00-04:00",
    "endTime": "2019-03-14T17:50:00-04:00",
    "appointmentTypeCode": 3,
    "intakeMetadata": {
        "concerns": [
            {
                "customCode": {
                    "code": 2305,
                    "description": "Fever (100+)"
                },
                "isPrimary": true
            }
        ],
        "additionalNotes": ""
    },
    "encounterTypeCode": 3,
    "paymentRequisites": {
        "cimProfileId": "15886118",
        "consultationAmount": 7
    },
    "where": "+1-34011111",
    "whereUse": "1",
    "serviceTypeId": 307
}

Sample response (error in data)

Status: 400 Sp Error 1000404 ExError 0

{
    "responseCode": 1000400,
    "message": "Appointment time should be set in the future",
    "spCallResult": {
        "DbName": "ConnectedCareTest",
        "Result": "[]",
        "Duration": 260.5497,
        "ErrorCode": 1000400,
        "Error": "Appointment time should be set in the future",
        "ExErrorCode": 0,
        "ExError": ""
    }
}

Sample response (not authorized)

Status: 401 Only patients are authorized to use this API

Contents

Clone this wiki locally