How to create an Appointment

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.

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

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
`pickupDeliveryTripEvent`	`Object`	The details of pickup delivery trip for an appointment	No

Sample 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,
    "sarCheckinDataDTO": null,
    "pickupDeliveryTripEvent": null,
    "sdSessionId": null
  }
}
'

Endpoints to get various constraint required in create appointment Request

Search for a Customer

curl --location --request GET 'https://api.mykaarma.com/customer/v2/department/{{dept_uuid}}/customer/list?searchTerm={{test_vin}}&searchPreference=vehicle&maxResults=50' \
--header 'Authorization: {{basic_auth_token}}'

Note: If no customer is found, create the customer first, add the vehicle to the customer's profile, and then proceed to call the create appointment endpoint. For detailed explanation please go through this page.

Search Customer - Exact

curl --location --request POST 'https://api.mykaarma.com/customer/v2/customer/list/exact' \
--header 'Authorization: {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "dealerUUIDList": [
    "{{dealer_uuid}}"
  ],
  "includeDealerOrderInfo": false,
  "maxResults": 150,
  "searchMap": {
    "COMMUNICATIONVALUE_EXACT": [
      "{{phone_number}}"
    ]
  }
}'

Get a customer's details: You'll need to use the customer UUID you'd have received from previous request(s)

curl --location --request GET 'https://api.mykaarma.com/customer/v2/department/{{dept_uuid}}/customer/{{test_vin_customer_uuid}}' \
--header 'Authorization: {{basic_auth_token}}'

Get Opcodes [DEPRECATED]:
Please refer to this page.

curl --location --request POST 'https://api.mykaarma.com/appointment/v2/department/{{dept_uuid}}/fetch/opcodes' \
--header 'Authorization: {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "communicationCodes": [],
    "dealerAppSchedulerVisibility": null,
    "dealerUUIDList": [],
    "endPosition": null,
    "eventDealerAssociateUuid": null,
    "getMkAndDmsSimilarOpcodeCount": true,
    "getTotalCount": true,
    "isLastPage": true,
    "mobileServiceVisibility": null,
    "onlineSchedulerVisibility": true,
    "opCodes": [],
    "requesterUserUUID": "string",
    "resultSize": null,
    "searchToken": null,
    "serviceCartVisibility": null,
    "sortDirection": "ASCENDING",
    "sortPreference": "OPCODE",
    "startPosition": 0,
    "uuidList": []
}'

Get Advisors:
For detailed explanation please go through this page.

curl --location --request GET 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/eligibleAdvisor/list' \
--header 'Authorization: {{basic_auth_token}}'

Get Transport options:
For detailed explanation please go through this page.

curl --location --request GET 'https://api.mykaarma.com/appointment/v2/department/{{dept_uuid}}/transportOption/list' \
--header 'Authorization: {{basic_auth_token}}'

Get Team List:
For detailed explanation please go through this page.

curl --location 'https://api.mykaarma.com/manage/v2/department/3fed82861160717ea55057293650d3f0e63903c756ec1b85b261a70390ff0d6f/dealerAssociateGroup/list' \
--header 'Authorization: {{basic_auth_token}}'

Get Appointment Slots:

{{dealerDepartmentUuid}} - Department Uuid of the user who wants to see the available slots
For detailed explanation please go through this page.

curl --location 'https://api.mykaarma.com/appointment/v2/department/{{dealerDepartmentUuid}}/availability' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json'
--data '{
    "requesterUserUUID": "string",
    "dealerUUIDList": "string",
    "platform": {
        "id": 0,
        "name": ""string""
    },
    "dates": [
        "string"
    ],
    "startTime": "string",
    "endTime": "string",
    "existingAppointmentUuid": "string",
    "customerInformation": {
        "firstName": "string",
        "lastName": "string",
        "company": "string",
        "customerKey": "string",
        "uuid": "string"
    },
    "customerPhones": [
        "string"
    ],
    "customerEmails": [
        "string"
    ],
    "vehicleInformation": {
        "brand": "string",
        "dealerUuid": "string",
        "engine": "string",
        "mileage": 10000,
        "model": "string",
        "trim": "string",
        "uuid": "string",
        "vehicleKey": "string",
        "vin": "string",
        "year": "string"
    },
    "selectedAvailabilityAttributes": {
        "dealerAssociateUuidList": [
            "string"
        ],
        "transportOptionUuidList": [
            "string"
        ],
        "subTransportOptionUuidList": "string",
        "teamUuidList": [
            "string"
        ]
    },
    "allAvailabilityAttributes": {
        "dealerAssociateUuidList": [
            "string"
        ],
        "transportOptionUuidList": [
            "string"
        ],
        "subTransportOptionUuidList": null,
        "teamUuidList": [
            "string"
        ]
    },
    "selectedOperationUuidSet": [
        "string"
    ],
    "selectedRecallOemIdSet": [],
    "callerDaUuid": "string",
    "subscriberName": "string",
    "refreshPanelSelectionState": true,
    "randomStringIdentifierForEditAppointment": "string"
}'

How to create an Appointment

Request​

HTTP request​

Parameters​

Path parameter:​

Authorization​

Request Body​

Sample Curl​

Endpoints to get various constraint required in create appointment Request​