How to create an appointment

This document is designed to help you understand how to create an appointment in myKaarma, what all parameters would you need, how to fetch them and then use them to best suit your use case.

You can create appointments in myKaarma for customer visits so that your Service Advisors are aware of their daily schedule and your customers could be notified/reminded for their scheduled visit.

To create an appointment, you first need your credentials. If you don't already have one, head over to the Authentication and Authorization page to see how you can request for credentials from us.

Parameters

Path parameter:

Required path parameters for process :

Parameter Name	Type	Description
`departmentUUID`	`string`	Unique identifier of dealer's department
`dealerUuid`	`String`	Unique identifier of dealer

Scope

This process requires the following authorization scopes :

Scope	Level	Description
`customer.search`	`DealerDepartment`	Authorizes client to search for customers for provided user's dealer department
`customer.update`	`DealerDepartment`	Authorizes client to create customer for provided user's dealer department
`kopcode.operation.read`	`Dealer`	Authorizes client to get operation codes for given dealership
`kopcode.factory.menu.read`	`Dealer`	Authorizes client to get factory-menus for given dealership
`appointment.configuration`	`Dealer`	Authorizes client to get eligible advisor for the provided dealer
`appointment.transportOptions`	`DealerDepartment`	Authorizes client to get transportOption for a dealer
`manage.dealerassociate.group`	`DealerDepartment`	Authorizes client to manage dealerassociate group

The following endpoints can help you with forming a proper request to create an appointment:

Process

To create an appointment in myKaarma, follow these steps based on your use case.

Decision Tree

Search for a Customer: Please refer to search and then create customer documentation. For this process, you will need to get UUID of the customer and vehicle.
Get services/opcodes: Please refer to get opcodes and menus. For this process, you can get the UUIDs of these services and operation Types. Alternatively, you can also use the laborOpcodes of these services. This endpoint gives only OPCODE and SERVICEMENU operation Types. Please use that information while creating an Appointment.
Get factory menus: Note - This is an Optional Step. Please refer to get factory menus. For this process, you can get the UUIDs of these services and operation Types. This endpoint gives only SERVICEMOTORSMAINTENANCEMENU operation Type. Please use that information while creating an Appointment.
Get Advisors: If your use case doesn't need a specific advisor to whom an appointment will be assigned, you can skip this step. You can pass the 'assignedUser' field as null. If it does require a specific advisor, then you will to find the UUID of this advisor. Please refer to get eligible advisors to find the UUID for your particular advisor.
Get Transport options: If your use case doesn't require any particular transport option or the transport option is 'None' for the appointment, you can pass 'transportOption' field as null. If it requires a different transport option, go through this page to obtain the UUID of the required transport option.
Get Team List: Teams are basically group of advisors created at the dealership. Let us say dealership wants appointments of a particular vehicle go to only a group of advisors, teams are helpful in such a setup. Again, if your use case is of no particular advisor then you can send 'teamUuid' as null and skip this step. If it is not, then please go through this page and check which teams have the UUID of the advisor you want to be assigned to the appointment and then select a team of your choice. Store the team's UUID for further processing.
Get slots available for appointment: Now you have all the parameters needed to create the appointment ready and need to find an available slot to schedule the appointment. Please note that availability of slots depend on various parameters:

Customer information
Vehicle information
Advisor to which appointment is assigned.
Team of the advisor to which appointment is assigned.
Services related to the appointment.
Transport option related to the appointment.

You have obtained the unique identifiers of all these parameters in previous steps of this process. You have to pass these identifiers in the availability request. Please note:

It is advised to fetch availability everytime one of these parameters is added/changed.
There are limits on how many appointments can be scheduled per transport option, advisor or dealership on slot, date and day level. Thus, availability also may change whenever an appointment is scheduled. The appointment can be scheduled from any myKaarma client or any other API partners. Keeping this in mind, it is advised to fetch availability right before scheduling the appointment.

For detailed explanation on how to get the available slots, refer to this page.

Request

HTTP request

POST  https://api.mykaarma.com/appointment/v2/dealer/{dealerUuid}/appointment

Parameters

Path parameter:

Parameter Name	Value	Description	Required
`dealerUuid`	`String`	Unique identifier of dealer	Yes

Authorization

This request requires the following authorization scopes:

Scope	Level	Description
`appointment.create`	`Dealer`	Authorises client to create appointment for the provided dealer

Request Body

Property Name	Value	Description	Required
`customerUuid`	`String`	Unique token assigned to each customer in myKaarma	Yes
`vehicleInformation`	`Object`	Details of the vehicle for which appointment is to be created such as - `vin` , `vehicleKey` , `vehicleUuid`	Yes
`appointmentStartDateTime`	`String`	The preferred start date-time of the appointment in yyyy-MM-ddTHH:mm:ss format	Yes
`appointmentEndDateTime`	`String`	The preferred end date-time of the appointment in yyyy-MM-ddTHH:mm:ss format	No
`transportation`	`String`	Option Name of transport option fetched using 'Get Transport options' endpoint. Example: Loaner	No
`transportOptionUuid`	`String`	UUID of transport option fetched using 'Get Transport options' endpoint. Example: -f_LNZEWiHQg4AbTH-b_qmDTO8CKwkSQXCtpYFHfWGw	No
`altTransportation`	`String`	Custom Name of transport option fetched using 'Get Transport options' endpoint. Example: Loaner	No
`assignedUser`	`Obejct`	The details of the dealer associate to whom the appointment is assigned	No
`creatorUser`	`Object`	The details of the dealer associate who created the appointment	No
`appointmentKey`	`String`	Unique token assigned to each appointment in DMS	No
`comments`	`String`	Comments/remarks for the appointment taken as customer's notes	No
`internalNotes`	`String`	Internal notes for the appointment which are intended for the dealership personnel only and not for the customer's visibility	No
`serviceList`	`Object`	List of services to be performed on the customer's vehicle for the appointment. It contains field like title, description, operationType etc. title: Title of the service (also referred as labor opcode) description: Description of the service operationType: There are 3 supported operation types - OPCODE, SERVICEMENU, SERVICEMOTORSMAINTENANCEMENU.	No
`customerAppointmentPreference`	`Object`	Preferences for customer communication	No
`status`	`Object`	Status of the appointment	No
`recall`	`Boolean`	Whether the appointment includes a recall	No
`pushToDms`	`Boolean`	Whether the appointment should be pushed to DMS	No

Explaining objects in request body

vehicleInformation

Property Name	Value	Description	Required
`vin`	`String`	Vehicle Identification Number - unique code used by automotive industry to identify vehicle	No
`vehicleKey`	`String`	Unique key of vehicle in the DMS	No
`vehicleUuid`	`String`	Unique identifier of vehicle in myKaarma	No

Note

None of the fields in this object are required but if you want a vehicle to be associated with the appointment, please pass one of these fields in the vehicleInformation object. You will get the UUID of the vehicle in the same process of getting a customer. Please refer to search and then create customer documentation.

assignedUser

Property Name	Value	Description	Required
`uuid`	`String`	Unique identifier of the user	No
`deptUUID`	`String`	Unique identifier of the department of the user	No
`teamUuid`	`String`	Unique identifier of the team user belongs to	No

Note

Send this object as null if your use case doesn't require an appointment to be assigned to any of the users. Our system will automatically assign the appointment to one of the advisors depending on their availability. If you want the appointment to be assigned to a specific user, we would recommend sending the uuid and deptUUID fields. If deptUUID is not sent, we would be default pick the UUID of service department of the dealership. You can get these fields from the response of get eligible advisors. 'userUuid' would map to uuid field in this object and "uuid" field of "department" object in the response would map to 'deptUUID'.

creatorUser

Property Name	Value	Description	Required
`uuid`	`String`	Unique identifier of the user	No
`deptUUID`	`String`	Unique identifier of the department of the user	No
`teamUuid`	`String`	Unique identifier of the team user belongs to	No

Note

This object is similar to assignedUser in terms of fields. You can pass this as null if your use case doesn't need a specific creator for the appointment. If not, follow the same steps as the assignedUser.

customerAppointmentPreference

Property Name	Value	Description	Required
`emailConfirmation`	`Boolean`	Decides whether to send an email for appointment confirmation	No
`textConfirmation`	`Boolean`	Decides whether to send an text for appointment confirmation	No
`emailReminder`	`Boolean`	Decides whether to send a reminder email for appointment	No
`textReminder`	`Boolean`	Decides whether to send a reminder text for appointment	No
`notifyCustomer`	`Boolean`	Decides whether to send appointment notifications to the customer	No
`sendCommunicationToDA`	`Boolean`	Whether to send appointment communications to the dealer associate	No
`confirmationEmail`	`String`	Email ID of customer where appointment confirmation email should be sent	No
`confirmationPhoneNumber`	`String`	Phone number of the customer where appointment confirmation text should be sent	No

Note

None of the fields are required. If you do not want communication with the customer to be done from myKaarma, send this object as null. If you want communication with the customer to be done from myKaarma, 'notifyCustomer' will be the umbrella boolean that has to be sent as true. Send other boolean depending on your use case whether you want communication through text or email and whether you want to send reminders or not. Reminders typically go out a day before the appointment. If you want the user to get notifications of the communication to customer, send this 'sendCommunicationToDA' field as true.

status

To create an appointment, our recommendation would be to send this as null. This is actually an enum that can take these values - CANCELLED, FAILED, UPDATED, Rescheduling Requested, Cancellation Requested, Show, No Show, Rescheduled, Updated, Confirmed, Scheduled, Reminder Sent, Cancelled. This status updates as the journey of the appointment happens in myKaarma.

serviceList

Note

This is not a required field. Send this as null if you don't want any opcodes/services to be attached to your appointment. We will save the service lines with as many details as you send us. For details exactly as they are in our system, just send the 'operationUuid' or 'title' field. 'title' maps to "laborOpCode" and 'operationUuid' maps to "uuid" of the response to get opcodes and menus.

Property Name	Value	Description	Required
`title`	`String`	laborOpCode of the opcode - unique code assigned to every service	No
`description`	`String`	Description of the opcode/service	No
`opCodeName`	`String`	Name of the opcode/service	No
`price`	`String`	Price of the opcode/service	No
`laborTotal`	`String`	Total labor price of the opcode/service	No
`partsTotal`	`String`	Total parts price of the opcode/service	No
`shopFees`	`String`	Price of the shop of the opcode/service	No
`taxes`	`String`	Taxes to be applied for the opcode/service	No
`payType`	`String`	What is the pay type of the opcode/service, ex. Customer, Warranty, Internal, etc.	No
`sortOrder`	`String`	Defines at what place in the list will the opcode/service show	No
`recallID`	`String`	ID of the recall associated with the opcode/service	No
`parentTitle`	`String`	This is valid only for menus and not opcodes. The laborOpCode of the opcode associated with the menu	No
`menuUuid`	`String`	This is valid only for menus and not opcodes. Unique identifier of the menu	No
`operationType`	`String`	What is the type of service. The default is OPCODE. It can be OPCODE, SERVICEMENU, SERVICEMOTORSMAINTENANCEMENU, SERVICEMOTORSLINEITEM, SERVICEMOTORSINDICATOR.	No
`operationUuid`	`String`	Unique identifier to the opcode/service	No
`isCustomConcern`	`String`	This tells whether the opcode/service is present at dealership or there is a custom request from customer	No
`durationInMins`	`String`	The time opcode/service takes in mins	No
`parentOpcodeUuid`	`String`	This is valid only for menus and not opcodes. The UUID of the opcode associated with the menu	No

Curl for appointment with no specific advisor, team and transport option.

curl --location --request POST 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/appointment' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerUuid": "{customer_uuid}",
  "vehicleInformation": {
    "vehicleUuid": "{vehicle_uuid}"
  },
  "appointmentInformation": {
    "appointmentStartDateTime": "{appointment_start_date_time e.g 2024-10-25T11:15:00}",
    "appointmentEndDateTime": "{appointment_end_date_time e.g 2024-10-25T11:29:59}",
    "trasportOption": null,
    "transportOption": null,
    "assignedUser": null,
    "creatorUser": null,
    "appointmentKey": null,
    "mileageText": null,
    "comments": "\n",
    "internalNotes": "",
    "serviceList": [
        {
        "title": "{labor_opcode}",
        "operationUuid": {operation_uuid},
        "isCustomConcern": false,
        "operationType": "{operation_type}",
      }
    ],
    "customerAppointmentPreference": {
      "emailConfirmation": false,
      "textConfirmation": false,
      "emailReminder": false,
      "textReminder": false,
      "confirmationEmail": "{email}",
      "confirmationPhoneNumber": "310XXXXXXX",
      "notifyCustomer": true,
      "sendCommunicationToDA": true
    },
    "status": null,
    "recall": false,
    "reminderCount": 0,
    "isOverridden": false,
    "overrideFutureNoPrefAppointment": false,
    "pushToDms": true,
    "draftUuid": null,
    "pdrToOpcodes": {},
    "deferredRecallDTOList": null,
    "pickupDeliveryTripEvent": null,
    "sdSessionId": null
  }
}
'

Complete Curl

curl --location --request POST 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/appointment' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerUuid": "fdgdfdfretertegbv43-A9ujPPd-M",
  "vehicleInformation": {
    "vin": null,
    "vehicleKey": null,
    "vehicleUuid": "kdFmlaWcUCWMAdZotP3fgdfVnOKHge56t0NXuG4QpXdWY"
  },
  "appointmentInformation": {
    "appointmentStartDateTime": "2024-10-25T11:15:00",
    "appointmentEndDateTime": "2024-10-25T11:29:59",
    "trasportOption": {
      "altTransportation": null,
      "transportation": null,
      "transportOptionUuid": "dfsdsf43tfxs-pCn0VBtnCur1AsjPwkH2RHUpf89LiMU",
      "bookingID": null,
      "bookInThirdParty": false
    },
    "transportOption": null,
    "assignedUser": {
      "uuid": "6bed86cc14791jkbdsf85a396610a3a84737546a0dd4ed23f522f90c91fe0",
      "deptUUID": "8ec821aefe98664ab15dfwrtrgfdghl0b1aeda9ff58df3db89bb0a55a3",
      "teamUuid": null
    },
    "creatorUser": {
      "uuid": "80c9166f65eecad91e3855555svdgerfg3e5d7a95841c3a2a7086d1c87a",
      "deptUUID": "8ec821aefe9twr42f34f26c3c46f9c37d0b1aeda9ff58df3db89bb0a55a3",
      "teamUuid": null
    },
    "appointmentKey": null,
    "mileageText": null,
    "comments": "\n",
    "internalNotes": "",
    "serviceList": [
        {
        "title": "CECOIL",
        "description": "CECOIL",
        "opCodeName": null,
        "price": null,
        "laborTotal": null,
        "partsTotal": null,
        "shopFees": null,
        "taxes": null,
        "payType": null,
        "sortOrder": 2,
        "recallID": null,
        "parentTitle": null,
        "menuUuid": null,
        "laborOpCode": null,
        "operationType": "OPCODE",
        "operationUuid": null,
        "isCustomConcern": false,
        "durationInMins": null,
        "parentOpcodeUuid": null
      }
    ],
    "customerAppointmentPreference": {
      "emailConfirmation": false,
      "textConfirmation": false,
      "emailReminder": false,
      "textReminder": false,
      "confirmationEmail": "test@gmail.com",
      "confirmationPhoneNumber": "310XXXXXXX",
      "notifyCustomer": true,
      "sendCommunicationToDA": true
    },
    "status": null,
    "recall": false,
    "reminderCount": 0,
    "isOverridden": false,
    "overrideFutureNoPrefAppointment": false,
    "pushToDms": true,
    "draftUuid": null,
    "pdrToOpcodes": {},
    "deferredRecallDTOList": null,
    "pickupDeliveryTripEvent": null,
    "sdSessionId": null
  }
}
'

Parameters​

Path parameter:​

Scope​

Process​

Request​

HTTP request​

Parameters​

Path parameter:​

Authorization​

Request Body​

Explaining objects in request body​

vehicleInformation​

assignedUser​

creatorUser​

customerAppointmentPreference​

status​

serviceList​

Curl for appointment with no specific advisor, team and transport option.​

Complete Curl​

Parameters

Path parameter:

Scope

Process

Request

HTTP request

Parameters

Path parameter:

Authorization

Request Body

Explaining objects in request body

vehicleInformation

assignedUser

creatorUser

customerAppointmentPreference

status

serviceList

Curl for appointment with no specific advisor, team and transport option.

Complete Curl