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 Name	Value	Description	Required
departmentUUID	String	Unique identifier of dealer department	Yes

Request parameter:

Parameter Name	Value	Description	Required
refreshSelectionState	Boolean	If 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
fetchAvailability	Boolean	If 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:

Scope	Level	Description
appointment.configuration	DealerDepartment	Authorises client to fetch availability for the provided dealer department

Request Body

Property Name	Value	Description	Required
requesterUserUUID	String	UUID of the user who is making this request	No
dealerUUIDList	List<String>	List of dealer UUIDs for which we want to compute first available slot	No
platform	Object	Specify the platform from which request is coming. eg - dealerApp , Web etc	No
dates	Set<String>	Dates for which availability needs to be fetched where each date is in yyyy-MM-dd format	Optional if service subscriber is mkConsumer otherwise required.
startTime	String	Time from which we want to compute availability. It should be in the format - HH:mm:ss	No
endTime	String	Time till which we want to compute availability. It should be in the format - HH:mm:ss	No
existingAppointmentUuid	String	Appointment UUID when updating an existing appointment	No
customerInformation	Object	Contains selected customer information such as - firstName , lastName, company , customerKey, uuid on which rules can apply	No
customerPhones	List<String>	List containing selected customer's phone numbers	No
customerEmails	List<String>	List containing selected customer's email address	No
vehicleInformation	Object	Contains information about selected customer's vehicle such as - vin , make , year , model , brand etc	No
selectedAvailabilityAttributes	Object	Specifies the selected attributes based on which availabilities needs to be fetched. These attributes are - dealerAssociateUuidList, transportOptionUuidList,subTransportOptionUuidList,teamUuidList	No
allAvailabilityAttributes	Object	All 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 acceptable	No
selectedOperationUuidSet	Set<String>	Set of opcode/service UUIDs that user has selected	No
selectedRecallOemIdSet	Set<String>	Set of OEM IDs of recalls that the user has selected	No
callerDaUuid	String	UUID of dealership personnel who is making this request	Required if service subscriber is mkDealer Otherwise optional.
subscriberName	String	Name of the subscriber from where the request is coming from.	No
refreshPanelSelectionState	Boolean	If 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
randomStringIdentifierForEditAppointment	String	Auto generated random identifier which is sent with the request body when editing an appointment through mK desktop scheduler	No

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 Name	Description
dealerHoursOfOperationStartTime	String of the format HH:mm:ss signifying the operation start time of the dealership
dealerHoursOfOperationEndTime	String of the format HH:mm:ss signifying the operation end time of the dealership
panelSelectionStateMap	A 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.
availabilityInfoMap	A 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.