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.	Yes
`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

caution

To get available slots in response, send fetchAvailability as true. Otherwise you can get unavailable slots and mark them as unavailable from the complete hours of operation of dealer.

Authorization

This request requires the following authorization scopes:

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

caution

In the request body below, many fields are marked as not required but it is advised to send all the parameters (like information of vehicle, ) in selected attributes that you will be using to schedule appointment. Downside of not sending these parameters may be the slot that comes as available when getting availability may actually not be available when we check with those parameters before scheduling appointment, resulting in appointment create/update failures.

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

caution

For date ranges, the recommended maximum value is 21 days. For any availability beyond 21 days, it is advised to make sequential calls of 21 days and aggregate responses.

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.

Want to find out what entities (Transport Option, Advisor, Team) will have no available slot

Running into situations where you get no available slots for your selected parameters?
This can happen when assignment rules configured at the dealership restrict certain combinations.

For example:

Rule: No loaner for opcode PO20K

If your request selects Loaner as the transport option and includes opcode PO20K, no available slots will be returned.

Use Case

You can proactively detect such rule violations before fetching actual time slots by calling the availability API without any dates.
This allows you to know which entities (advisor, team, transport option) are disabled for your selected attributes — and you can filter them out in your UI.

Typical flow example:

User selects Vehicle
User selects Services (opcodes or recalls)
User selects Transport Option

At this stage, you can fire a pre-check availability request with no dates and include all other known parameters — such as customer details, VIN, selected opcodes, recalls, etc.

HTTP Request

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

Request Body

Pass all the available information you have so far — for example:

Property Name	Description	Required
`customerInformation`	Contains selected customer details such as name, company, and UUID	No
`vehicleInformation`	Vehicle details like `vin`, `make`, `model`, `year`	No
`selectedOperationUuidSet`	Set of opcode/service UUIDs selected by the user	No
`selectedAvailabilityAttributes`	Contains selected UUIDs of Dealer Associates, Teams, or Transport Options	No
`dates`	Omit this field for pre-check requests	No

Response

The response will contain a panelSelectionStateMap object that categorizes each entity as selected, unselected, or disabled.

Look specifically for the following keys:

Key	Description
`selectedEntityUuidSet`	UUIDs of entities currently selected
`unselectedEntityUuidSet`	UUIDs of available but unselected entities
`disabledEntityUuidToWarningsMap`	UUIDs of entities disabled due to rule violations, along with warning details

Sample Response

{
  "panelSelectionStateMap": {
    "TRANSPORT_OPTION": {
      "selectedEntityUuidSet": [
        "Uuid"
      ],
      "unselectedEntityUuidSet": [
        "CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q",
        "w5fkIJojY4v-pCn0VBtnCur1AsjPwkH2RHUpf89LiMU"
      ],
      "disabledEntityUuidToWarningsMap": {
        "-f_LNZEWiHQg4AbTH-b_qmDTO8CKwkSQXCtpYFHfWGw": [
          {
            "warningCode": "ASSIGNMENT_RULE_VIOLATED",
            "warningDescription": "Rule = \"No loaner for special opcode\" is violated."
          }
        ]
      }
    }
  }
}

How to Use the Response

Inspect the disabledEntityUuidToWarningsMap to identify entities (e.g., Loaner Transport Option) that are unavailable for the selected combination.
Use this information to disable or hide those options in your UI.
Optionally, display the warningDescription as an explanatory message to the user — for example:
"Loaner is not available with the selected service."

After the user selects valid entities, you can proceed with a normal availability request with dates (and optionally fetchAvailability=true to get only available slots).

Request​

HTTP request​

Parameters​

Path parameter:​

Request parameter:​

Authorization​

Request Body​

Sample Request Model​

Sample Curl​

Response​

Summary of Response​

Sample availabilityInfoMap for Date​

Sample availabilityInfoMap for Date and Time​

Sample availabilityInfoMap for ALL_DATE_TIME​

Want to find out what entities (Transport Option, Advisor, Team) will have no available slot​

Use Case​

HTTP Request​

Request Body​

Response​

Sample Response​

How to Use the Response​

Request

HTTP request

Parameters

Path parameter:

Request parameter:

Authorization

Request Body

Sample Request Model

Sample Curl

Response

Summary of Response

Sample availabilityInfoMap for Date

Sample availabilityInfoMap for Date and Time

Sample availabilityInfoMap for ALL_DATE_TIME

Want to find out what entities (Transport Option, Advisor, Team) will have no available slot

Use Case

HTTP Request

Request Body

Response

Sample Response

How to Use the Response