Skip to main content

How to get resource availabilities

Get the availabilities of advisors, transport options and teams as per the selected attributes including opcodes, recalls, customer and their chosen vehicle for the specified dates.

Request

HTTP request

POST  https://api.mykaarma.com/appointment/v2/department/{{departmentUUID}}/availability?refreshSelectionState

Parameters

Path parameter:

Parameter NameValueDescriptionRequired
departmentUUIDStringUnique identifier of dealer departmentYes

Request parameter:

Parameter NameValueDescriptionRequired
refreshSelectionStateBooleanIf set to true, it returns the state of panel and categorises each entity - Dealer Associate , Team and Transport Option into either selected , unselected or disabled. Availabilities are only returned for the selected entities.No
fetchAvailabilityBooleanIf set to true, it returns only available slots instead of unavailable slots for each combination of selected Dealer Associate , Team and Transport Option.No

Authorization

This request requires the following authorization scopes:

ScopeLevelDescription
appointment.configurationDealerDepartmentAuthorises client to fetch availability for the provided dealer department

Request Body

Property NameValueDescriptionRequired
requesterUserUUIDStringUUID of the user who is making this requestNo
dealerUUIDListList<String>List of dealer UUIDs for which we want to compute first available slotNo
platformObjectSpecify the platform from which request is coming. eg - dealerApp , Web etcNo
datesSet<String>Dates for which availability needs to be fetched where each date is in yyyy-MM-dd formatOptional if service subscriber is mkConsumer otherwise required.
startTimeStringTime from which we want to compute availability. It should be in the format - HH:mm:ssNo
endTimeStringTime till which we want to compute availability. It should be in the format - HH:mm:ssNo
existingAppointmentUuidStringAppointment UUID when updating an existing appointmentNo
customerInformationObjectContains selected customer information such as - firstName , lastName, company , customerKey, uuid on which rules can applyNo
customerPhonesList<String>List containing selected customer's phone numbersNo
customerEmailsList<String>List containing selected customer's email addressNo
vehicleInformationObjectContains information about selected customer's vehicle such as - vin , make , year , model , brand etcNo
selectedAvailabilityAttributesObjectSpecifies the selected attributes based on which availabilities needs to be fetched. These attributes are - dealerAssociateUuidList, transportOptionUuidList,subTransportOptionUuidList,teamUuidListNo
allAvailabilityAttributesObjectAll the UUIDs of the attributes which are configured at the dealership . These attributes are - dealerAssociateUuidList, transportOptionUuidList,subTransportOptionUuidList,teamUuidList. Note- Ensure that either all UUIDs for each attribute are included, or none at all. Partial data is not acceptableNo
selectedOperationUuidSetSet<String>Set of opcode/service UUIDs that user has selectedNo
selectedRecallOemIdSetSet<String>Set of OEM IDs of recalls that the user has selectedNo
callerDaUuidStringUUID of dealership personnel who is making this requestRequired if service subscriber is mkDealer Otherwise optional.
subscriberNameStringName of the subscriber from where the request is coming from.No
refreshPanelSelectionStateBooleanIf set to true, it returns the state of panel and categorises each entity - Dealer Associate , Team , Transport Option into either selected , unselected or disabled . if the entity selected in request is unavailable due to assignment rules, the selected entity will be switched to an available one and availabilities of the switched entity will be returned.No
randomStringIdentifierForEditAppointmentStringAuto generated random identifier which is sent with the request body when editing an appointment through mK desktop schedulerNo

Sample Request Model

{
"allAvailabilityAttributes": {
"dealerAssociateUuidList": [
"string"
],
"subTransportOptionUuidList": [
"string"
],
"teamUuidList": [
"string"
],
"transportOptionUuidList": [
"string"
]
},
"callerDaUuid": "string",
"customerEmails": [
"string"
],
"customerInformation": {
"company": "string",
"customerKey": "string",
"firstName": "string",
"lastName": "string",
"uuid": "string"
},
"customerPhones": [
"string"
],
"dates": [
"string"
],
"dealerUUIDList": [
"string"
],
"endTime": "string",
"existingAppointmentUuid": "string",
"platform": {
"id": integer,
"name": "string"
},
"randomStringIdentifierForEditAppointment": "string",
"refreshPanelSelectionState": true,
"requesterUserUUID": "string",
"selectedAvailabilityAttributes": {
"dealerAssociateUuidList": [
"string"
],
"subTransportOptionUuidList": [
"string"
],
"teamUuidList": [
"string"
],
"transportOptionUuidList": [
"string"
]
},
"selectedOperationUuidSet": [
"string"
],
"selectedRecallOemIdSet": [
"string"
],
"startTime": "string",
"subscriberName": "string",
"vehicleInformation": {
"brand": "string",
"dealerUuid": "string",
"engine": "string",
"mileage": "string",
"model": "string",
"trim": "string",
"uuid": "string",
"vehicleKey": "string",
"vin": "string",
"year": "string"
}
}

Sample Curl

curl --location 'https://api.mykaarma.com/appointment/v2/department/{{departmentUUID}}/availability?refreshSelectionState=true' \
--header 'Authorization: {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data '{
"requesterUserUUID": null,
"dealerUUIDList": null,
"platform": {
"id": null,
"name": "DealerApp"
},
"dates": [
"2023-03-21",
"2023-03-20"
],
"startTime": null,
"endTime": null,
"existingAppointmentUuid": null,
"customerInformation": null,
"customerPhones": null,
"customerEmails": null,
"vehicleInformation": null
"selectedAvailabilityAttributes": {
"dealerAssociateUuidList": [
"64e07c212f74cf630f9f709fdc321d58e60433227bd5ad8758dfd9c8276fc473"
],
"transportOptionUuidList": [
"Uuid"
],
"subTransportOptionUuidList": null,
"teamUuidList": [
"XHXK76_bW2yRzGIp3uJsLno4HOmrOKpLIlraMD7jn3s"
]
},
"allAvailabilityAttributes": {
"dealerAssociateUuidList": [
"64e07c212f74cf630f9f709fdc321d58e60433227bd5ad8758dfd9c8276fc473",
"e946917fed3fdb82a8b1ace3aa55647cbbcd678e68f2ea50d1a2537a5865d9ff",
"d2d73272312a7868d219fd7b181697a23757222a01cafde3ef9b8b4cf78d20cb",
"2b54e0313aa6e4351d2cce3e5f133c768ca3c224403b8ade9709f502296288b5"
],
"transportOptionUuidList": [
"w5fkIJojY4v-pCn0VBtnCur1AsjPwkH2RHUpf89LiMU",
"qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0",
"CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q",
"Uuid"
],
"subTransportOptionUuidList": null,
"teamUuidList": [
"XHXK76_bW2yRzGIp3uJsLno4HOmrOKpLIlraMD7jn3s",
"ALL_ADVISORS_UUID"
]
},
"selectedOperationUuidSet": ["3V9k8y8f9Rr3p_L7Rgu7kr982vCDoyFyy2Oc1QMmln8","nQisOp04babYr7FpBBZfqOgda3q5VUcOfYakw1mntMY"],
"selectedRecallOemIdSet": [],
"callerDaUuid": "5b372a12f3b33348f096bdd0ee38cbf8d84b25a9c128edad4ff0462d0b3603fd",
"subscriberName": null,
"refreshPanelSelectionState": null,
"randomStringIdentifierForEditAppointment": null
}'

Response

{
"dealerHoursOfOperationEndTime": "string",
"dealerHoursOfOperationStartTime": "string",
"panelSelectionStateMap": {
"panel": {
"selectedEntityUuidSet": [
"string"
],
"unselectedEntityUuidSet": [
"string"
],
"disabledEntityUuidToWarningsMap": {
"string": [
{
"warningCode": "string",
"warningDescription": "string"
}
]
}
}
},
"availabilityInfoMap": {
"string": {
"string": {
"vacant": false,
"warningMap": {
"string": [
"string"
]
}
}
}
},
"error": {
"errorCode": "string",
"errorDescription": "string",
"errorUID": "string"
},
"statusCode": 0,
"warnings": [
{
"warningCode": "string",
"warningDescription": "string"
}
]
}

Summary of Response

Parameter NameDescription
dealerHoursOfOperationStartTimeString of the format HH:mm:ss signifying the operation start time of the dealership
dealerHoursOfOperationEndTimeString of the format HH:mm:ss signifying the operation end time of the dealership
panelSelectionStateMapA map of type Map<Panel, SelectionState> where Panel refers to each of the selection panel/entity - DEALER_ASSOCIATE , TRANSPORT_OPTION, TEAM.
SelectionState tells the state of the corresponding panel by maintaining -selectedEntityUuidSet - a set containing UUIDs of selected entities, unselectedEntityUuidSet - a set containing UUIDs of unselected entities and disabledEntityUuidToWarningsMap - a mapping between the UUID of disabled entity to list of reasons for its unavailability.
State of the panel is used to prevent users from creating appts with disabled entities.
availabilityInfoMapA map of type Map<String, Map<String, VacancyInfo>>. It tells which combination of Dealer Associate(assigned service advisor) , Transport Option and Team is unavailable when and for what reason.

Here the outer key is a string which contains information about date and time and can have 3 values -
1. Date (eg : 2023-03-26)
2. Date and Time (eg : 2023-03-26 12:00:00)
3. ALL_DATE_TIME
This key specifies whether it is applicable for only a specific date , specific date and time or it is always applicable irrespective of date and time.

The inner key is of the format DA={{DA_UUID}},TO={{TO_UUID}},TEAM={{TEAM_UUID}} , specifying the combination which is unavailable.

vacancyInfo is an object which contains isVacant which is always returned as false and a warningMap which tells the reasons why this particular combination in unavailable.

Sample availabilityInfoMap for Date

"availabilityInfoMap":{
"2023-11-29": {
"DA=149b70145a0989ad7d28f00f699ef9bb7357850c9eb3fdb15dc99a3af6743fd7,TO=recb8K8QYLpT0MQ2RcLZ88KvcIyTYbpi06jGC68FbG0,TEAM=null": {
"warningMap": {
"APPT_RULE_WARN_CAPACITY_PLANNING_CONSTRAINT_VIOLATED": [
"Rule = \"date rule\" is violated."
]
},
"vacant": false
}
},
}

In this the whole date 2023-11-29 is marked unavailable for the combination of DA, TO and Team.

Sample availabilityInfoMap for Date and Time

"availabilityInfoMap": {
"2023-12-13 08:15:00": {
"DA=a1cce52d69d94400649c4f6fc0d0cac3ddb70308c020cae443ad37df10b747d8,TO=Uuid,TEAM=null": {
"warningMap": {
"APPT_RULE_WARN_CAPACITY_PLANNING_CONSTRAINT_VIOLATED": [
"You have reached the maximum limit of (0) appointments for (:advisor) on (Wednesday).",
"The selected timeslot (08:15 AM - 08:29 AM) has been marked as unavailable in the Individuals Schedule of (:advisor) for (Wednesday).",
"You have reached the maximum limit of (33) appointments on (Wednesday)."
]
},
"vacant": false
}
},
}

In this slot of 08:15 on 2023-12-13 is marked unavailable for this "DA=a1cce52d69d94400649c4f6fc0d0cac3ddb70308c020cae443ad37df10b747d8,TO=Uuid,TEAM=null" combination of DA, TO and TEAM.
It contains a list of warning messages which shows the reason why a particular slot is unavailable for this particular combination of DA, TO and TEAM.
Similarly like this availabilityInfoMap contains all the unavailable slots with warnings.

Sample availabilityInfoMap for ALL_DATE_TIME

"availabilityInfoMap": {
"ALL_DATE_TIME": {
"DA=149b70145a0989ad7d28f00f699ef9bb7357850c9eb3fdb15dc99a3af6743fd7,TO=w5fkIJojY4v-pCn0VBtnCur1AsjPwkH2RHUpf89LiMU,TEAM=null": {
"warningMap": {
"APPT_RULE_WARN_CAPACITY_PLANNING_CONSTRAINT_VIOLATED": [
"Rule = \"assingnment rule\" is violated."
]
},
"vacant": false
}
}
}

In this all the slots for requested dates are marked unavailable for the combination of DA, TO and TEAM.
This type of response is generated in the case of assignment rule. Ex - If Opcode in XYZ then Service Advisor not in ABC.
Now if you choose Opcode XYZ and Service Advisor ABC then above assignment rule will be violated and all the slots will be marked unavailable.