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
`platform`	`Object`	Platform object in request body with `name` (String). API Partners should send the platform name as "Web".	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. API Partners should send the platform name as "Web". Other examples include `DealerApp`, 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": null,
    "name": "Web"
  },
  "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": "Web"
    },
    "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.

Sample availabilityInfoMap when fetchAvailability is true

When fetchAvailability is set to true in the request query parameter, the API returns only available slots instead of unavailable slots. This is useful when you want to display available time slots directly to users without having to compute unavailable slots from the dealer's hours of operation.

info

Key Difference: When fetchAvailability=true, the availabilityInfoMap contains only slots where vacant: true, making it easier to display available options to end users.

The structure of availabilityInfoMap varies based on what is passed in the selectedAvailabilityAttributes field. The inner key format is DA={{DA_UUID}},TO={{TO_UUID}},TEAM={{TEAM_UUID}} where:

DA = Dealer Associate (Service Advisor) UUID
TO = Transport Option UUID
TEAM = Team UUID

Below are examples for different scenarios:

a) No advisor or transport option UUID in selectedAvailabilityAttributes

Request scenario: Making the request without passing any advisor or transport option UUID in the selectedAvailabilityAttributes field.

Response structure:

"availabilityInfoMap": {
  "2026-02-20 13:15:00": {
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-20 13:30:00": {
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-20 12:45:00": {
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-19 14:30:00": {
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  }
}

Key points:

The DA UUID in every entry represents a default advisor configured for the dealer
Since no specific advisor was requested, the system uses the default advisor for all available slots
You can use any of these time slots when creating an appointment - the backend will assign an appropriate advisor automatically
TO=null indicates no transport option was specified in the request

b) One or more advisor UUIDs, no transport option UUID

Request scenario: Passing one or more advisor UUIDs in dealerAssociateUuidList and no transport option UUID in transportOptionUuidList within selectedAvailabilityAttributes.

Response structure:

"availabilityInfoMap": {
  "2026-02-20 13:15:00": {
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=a72e70d2a9eb3d82acd7259d74247a68a40477b7538f39992b39176203346980,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-20 13:30:00": {
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-20 12:45:00": {
    "DA=a72e70d2a9eb3d82acd7259d74247a68a40477b7538f39992b39176203346980,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-19 14:30:00": {
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=a72e70d2a9eb3d82acd7259d74247a68a40477b7538f39992b39176203346980,TO=null,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  }
}

Key points:

This example shows the response when 2 advisors were passed in the request and no transport option was specified
Time slot 2026-02-20 13:15:00: Both advisors (f6f24b0d... and a72e70d2...) are available
Time slot 2026-02-20 13:30:00: Only advisor f6f24b0d... is available
Time slot 2026-02-20 12:45:00: Only advisor a72e70d2... is available
Time slot 2026-02-19 14:30:00: Both advisors are available
TO=null in all entries indicates no transport option was requested

c) No advisor UUIDs, one or more transport option UUIDs

Request scenario: Passing no advisor UUIDs in dealerAssociateUuidList and one or more transport option UUIDs in transportOptionUuidList within selectedAvailabilityAttributes.

Response structure:

"availabilityInfoMap": {
  "2026-02-20 13:15:00": {
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-20 13:30:00": {
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-20 12:45:00": {
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-19 14:30:00": {
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=16c7b238173a7e740be1f99b0c347e8839a6841b675a0bd39239c88653faa417,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  }
}

Key points:

Since no advisor UUID was passed, the DA value in all entries is the default advisor configured for this dealer
This example shows the response when 2 transport options were passed (CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q and qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0)
Time slot 2026-02-20 13:15:00: Both transport options are available
Time slot 2026-02-20 13:30:00: Only transport option CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q is available
Time slot 2026-02-20 12:45:00: Only transport option qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0 is available
Time slot 2026-02-19 14:30:00: Both transport options are available

d) One or more advisor UUIDs and one or more transport option UUIDs

Request scenario: Passing one or more advisor UUIDs in dealerAssociateUuidList and one or more transport option UUIDs in transportOptionUuidList within selectedAvailabilityAttributes.

Response structure:

"availabilityInfoMap": {
  "2026-02-20 13:15:00": {
    "DA=a72e70d2a9eb3d82acd7259d74247a68a40477b7538f39992b39176203346980,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=a72e70d2a9eb3d82acd7259d74247a68a40477b7538f39992b39176203346980,TO=CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-20 13:30:00": {
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-20 12:45:00": {
    "DA=a72e70d2a9eb3d82acd7259d74247a68a40477b7538f39992b39176203346980,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  },
  "2026-02-19 14:30:00": {
    "DA=a72e70d2a9eb3d82acd7259d74247a68a40477b7538f39992b39176203346980,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=f6f24b0d63020012ae08ea5fa6acd9f88b5b60de8d8f7c705fbaf858bd81a100,TO=qhLQ5MDZWWsZOwy_YEtuvPhz6ZliEkjcrHSqFYdI-o0,TEAM=null": {
      "warningMap": null,
      "vacant": true
    },
    "DA=a72e70d2a9eb3d82acd7259d74247a68a40477b7538f39992b39176203346980,TO=CjaK5wAvBDG7Di6XAt6RpllbGtz9SiHoBzM2vDiFa9Q,TEAM=null": {
      "warningMap": null,
      "vacant": true
    }
  }
}

Key points:

The response contains all available combinations of advisor and transport option for each time slot
This example shows the response when 2 advisors (a72e70d2... and f6f24b0d...) and 2 transport options (qhLQ5MDZ... and CjaK5wAv...) were passed in the request
Each time slot shows which specific advisor-transport option combinations are available

Availability breakdown by time slot:

Time slot 2026-02-20 13:15:00: All 4 combinations are available (2 advisors × 2 transport options)
- Advisor a72e70d2... with transport option qhLQ5MDZ...
- Advisor f6f24b0d... with transport option CjaK5wAv...
- Advisor f6f24b0d... with transport option qhLQ5MDZ...
- Advisor a72e70d2... with transport option CjaK5wAv...
Time slot 2026-02-20 13:30:00: Only advisor f6f24b0d... is available, but both transport options work with this advisor (2 combinations)
Time slot 2026-02-20 12:45:00: Both advisors are available, but only transport option qhLQ5MDZ... is available (2 combinations)
Time slot 2026-02-19 14:30:00: All 4 combinations are available (2 advisors × 2 transport options)

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
`platform`	Platform object with `name` set to "Web" for API Partners	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​

Sample availabilityInfoMap when fetchAvailability is true​

a) No advisor or transport option UUID in selectedAvailabilityAttributes​

b) One or more advisor UUIDs, no transport option UUID​

c) No advisor UUIDs, one or more transport option UUIDs​

d) One or more advisor UUIDs and one or more transport option UUIDs​

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

Sample availabilityInfoMap when fetchAvailability is true

a) No advisor or transport option UUID in selectedAvailabilityAttributes

b) One or more advisor UUIDs, no transport option UUID

c) No advisor UUIDs, one or more transport option UUIDs

d) One or more advisor UUIDs and one or more transport option UUIDs

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