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`	`DealerDepartment`	Authorizes client to get operation codes 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. Alternatively, you can also use the laborOpcodes of these services.
Get Advisors: If your use case doesn't need a specific advisor to whom 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, etc. title: Title of the service (also referred as labor opcode) description: Description of the service	No
`customerAppointmentPreference`	`Object`	Preferences for customer communication	No
`emailConfirmation`	`Boolean`	Field in customerAppointmentPreference object stores whether to send an email for appointment confirmation	No
`textConfirmation`	`Boolean`	Field in customerAppointmentPreference object stores whether to send an text for appointment confirmation	No
`notifyCustomer`	`Boolean`	Field in customerAppointmentPreference object stores whether to send appointment notifications to the customer	No
`confirmationEmail`	`String`	Field in customerAppointmentPreference object stores email ID of customer where appointment confirmation email should be sent	No
`confirmationPhoneNumber`	`String`	Field in customerAppointmentPreference object stores phone number of the customer where appointment confirmation text should be sent	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
`draftUuid`	`String`	Unique token assigned to the corresponding draft appointment	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
      }
    ],
    "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": null,
        "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​

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

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

Complete Curl