How to get appointments in myKaarma
This document is designed to help you understand how you can get appointments made in the myKaarma system. Let's get started.
How to get all appointments create/update events in myKaarma
The most efficient and our recommended approach would be webhooks. This would make sure that you get real time updates of all events related to appointments in mykaarma.
To catch up on the appointments that have already been made, contact apisupport@mykaarma.com.
For detailed documentation on how to enable webhooks for your integration please refer to this page.
If for some reason, webhooks subscription doesn't work for you and you would like to use our APIs, though we think you should still be using webhooks :), please check if you want to get appointments by:
Get appointments by UUID
If you already have the UUID (unique identifier of the appointment in myKaarma), please go through this page on how to get appointment by UUID.
Get appointments by customer
Need to find appointments for a particular customer? Please go through this page on how to get appointments by customer. Please note this would require you to first fetch UUID of the customer - details on the linked page.
Get appointments by appointment date
If your use case requires you to search appointments by appointment date. Please go through this page on how to get appointments by appointment date.
Get appointment for a particular repair order
If you want to find an appointment linked to a particular repair order, please go through this page on how to get appointment for a particular repair order. Please note this would require you to first UUID of the repair order - details on the linked page.
Get appointments by filter
If none of the above cases fit your use case, then you can try using the get appointments by filter method desribed in detail on this page. This will help you fetch appointments by
- Appointment keys (Keys or identifiers of appointments in DMS).
- Created date (Date when appointment was created)
- Appointment date (For a range of dates when appointment is scheduled)
- Customers (Filter using UUIDs of customer)
- Appointments assigned to particular teams (Filter using UUIDs of teams)
- Created by (Check what appointments were created by dealer app or web scheduler or API)
Note this is a paginated endpoint with recommended limit of no more than 100 page size. We would advise to use this only if your use case is not satisfied by any of the other methods to get appointments.
The response of all the APIs to get appointments are similar.
Quick summary of get appointments by customer response fields
| Parameter Name | Description |
|---|---|
uuid | Unique identifier used by mykaarma to uniquely identify each appointment |
customerInformation.firstName | FirstName of the customer |
customerInformation.lastName | lastName of the customer |
customerInformation.company | company name of the customer provided if the customer is a BUSINESS customer |
customerInformation.isBusiness | True if the customer is a business customer |
customerInformation.customerKey | Key or identifier of the customer in DMS |
customerInformation.confirmationPhone | Phone number of the customer where confirmation text to be sent |
customerInformation.confirmationEmail | The email of the customer where confirmation email to be sent |
customerInformation.custLocale | The preferred language of the customer |
customerInformation.uuid | Unique identifier of the customer in myKaarma |
vehicleInformation.vehicleKey | Unique identifier used by DMS to uniquely identify each vehicle, used by mykaarma to lookup vehicles in DMS databases for various purposes like updation, deletion, booking appointment etc. |
vehicleInformation.uuid | Unique identifier used by mykaarma in addition to vehicles.id, used for uniquely identifying vehicles over API calls(for read, write, update, delete purposes) without revealing their database id that is vehicles.id |
vehicleInformation.year | the year when the vehicle was manufactured |
vehicleInformation.make | the brand of the vehicle |
vehicleInformation.engine | engine description of the vehicle |
vehicleInformation.trim | trim description of the vehicle |
vehicleInformation.model | model of the vehicle |
vehicleInformation.vin | VIN of the vehicle |
vehicleInformation.isValid | Indicates whether the customer currently owns the vehicle. |
orderInformation.uuid | UUID (unique identifier in myKaarma) of the repair order associated with this appointment |
orderInformation.orderNumber | Number of the repair order associated with this appointment |
orderInformation.orderDate | Date of the repair order associated with this appointment |
orderInformation.orderType | Type of the repair order associated with this appointment |
dealerUuid | UUID (unique identifier in myKaarma) of the dealer |
assignedAdvisorUuid | UUID (unique identifier in myKaarma) of the advisor to which appointment is assigned |
creatorAdvisorUuid | UUID (unique identifier in myKaarma) of the advisor who created the appointment |
assignedAdvisorDmsDepartmentCode | Dispatch code in DMS of the advisor to whom appointment is assigned. |
date | time stamp when appointment was created in YYYY-MM-DD HH:MM:SS format in PST timezone |
preferredDate | date of the appointment in YYYY-MM-DD format |
startTime | Start time of the appointment in YYYY-MM-DD HH:MM:SS format. This is dealership timezone. |
endTime | End time of the appointment in YYYY-MM-DD HH:MM:SS format. This is dealership timezone. |
transportOption.uuid | UUID (unique identifier in myKaarma) of the transport option associated to appointment |
transportOption.altTransportation | custom name of the transport option associated to appointment |
transportOption.bookingId | ID from third party if the loaner is booked in third party like TSD,etc. |
transportOption.bookInThirdParty | This would be true if loaner is booked in third party like TSD,etc. |
transportOption.bookingStartDate | Start date of the booking in third party like TSD, etc. |
transportOption.bookingEndDate | End date of the booking in third party like TSD, etc. |
transportOption.bookingIsManual | Is booking done manually in third party |
transportOption.bookingIsValid | Is booking in the third party valid? |
transportOption.loanerSmartLink | A link provided by third party to access loaner. |
transportOption.transportation | name of the transport option associated to appointment |
transportOption.subTransportOptionUuid | UUID of the subtransport option associated to appointment like Loaner in PnD. |
appointmentKey | Key or identifier in DMS of the appointment |
mileageText | custom name of the transport option associated to appointment |
recall | recall associated to appointment |
platform | Platform from which appointment was created like dealer app, web scheduler, DMS, etc. |
appointmentSource | Source from which appointment was created like dealer, DMS, API ,etc. |
newStatus | status of the appointment at this moment |
comments | Notes from customer for this appointment |
internalNotes | Notes from dealership personel for this appointment |
isCancelled | Is the appointment cancelled? |
reminderCount | Number of times the reminder has been sent for this appointment |
serviceList | A list of line items associated with the appointment |
serviceList.uuid | UUID of the opcode/service in this line item |
serviceList.opCode | Name of the opcode/service in this line item |
serviceList.laborOpCode | Unique code of the opcode/service in this line item |
serviceList.description | Description of the line item |
serviceList.operationType | What is the type of service. The default is OPCODE. It can be OPCODE, SERVICEMENU, SERVICEMOTORSMAINTENANCEMENU, SERVICEMOTORSLINEITEM, SERVICEMOTORSINDICATOR. |
serviceList.laborTotal | Total labor price of the opcode/service in this line item |
serviceList.partsTotal | Total parts price of the opcode/service in this line item |
serviceList.shopFees | Price of the shop of the opcode/service in this line item |
serviceList.taxes | Taxes to be applied for the opcode/service in this line item |
serviceList.price | Price of the line item |
serviceList.isValid | Whether the line item is valid or has been canceled |
serviceList.payType | What is the pay type of the line item, ex. Customer, Warranty, Internal, etc. |
serviceList.sortOrder | Defines at what place in the list will the line item show |
serviceList.parentOpcodeUuid | String |
serviceList.menuUuid | This is valid only for menus and not opcodes. Unique identifier of the menu |
serviceList.recallID | ID of the recall associated with the line item |
serviceList.durationInMins | `String |
serviceList.isCustomConcern | This tells whether the opcode/service is present at dealership or there is a custom request from customer |
serviceList.isDealerAddedLine | String |
skillList | A list of skills needed for the appointment |
skillList.uuid | UUID of the skill |
skillList.name | Name of the skill |
skillList.dealerUuid | UUID of the dealership associated with the skill |
skillList.departmentUuid | UUID of the department associated with the skill |
skillList.operationList | List of opcodes/services associated with the skill |
skillList.isValid | Whether skill is valid or not |
appointmentCommunicationPreferences | Preferences for communication like confirmation and reminder for the appointment |
appointmentCommunicationPreferences.emailConfirmation | Whether to send appointment confirmation email or not |
appointmentCommunicationPreferences.textConfirmation | Whether to send appointment confirmation text or not |
appointmentCommunicationPreferences.emailReminder | Whether to send appointment reminder email or not |
appointmentCommunicationPreferences.textReminder | Whether to send appointment reminder text or not |
appointmentCommunicationPreferences.confirmationEmail | Email to which confirmation has to be sent for the appointment |
appointmentCommunicationPreferences.textConfirmation | Phone number to which confirmation has to be sent for the appointment |
appointmentCommunicationPreferences.sendCommunicationToDA | Whether to send appointment communication copies to dealer associate |
teamUuid | UUID of the team associated with appointment |
dispatchCode | Dispatch code associated to appointment |
customerVehicleInspectionId | ID of the vehicle inspection |
sarmetaData.dmsMetaData.type | Type of DMS event associated with this metaData - PUSH or PULL |
sarmetaData.dmsMetaData.title | What happened for this DMS event - SUCCESS or FAILURE |
sarmetaData.dmsMetaData.description | Detail of the DMS event |
sarmetaData.dmsMetaData.vehicleUuid | UUID of the vehicle |
sarmetaData.dmsMetaData.dealerAssociateId | UUID of the dealer associate |
sarmetaData.appointmentData | Key value pair map to store appointment metadata |