How to create a draft Appointment

Create a sample draft appointment and generate a short URL for consumer scheduler with pre-filled information.

Request

HTTP request

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

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.draft.create	Dealer	Authorizes client to create draft appointments for a dealer

Request Body

Property Name	Value	Description	Required
appointmentCommunicationPreference	Object	Communication preferences for the appointment	No
appointmentEndDateTime	String	The preferred end date-time of the appointment in yyyy-MM-ddTHH:mm:ss format	No
appointmentStartDateTime	String	The preferred start date-time of the appointment in yyyy-MM-ddTHH:mm:ss format	Yes
assignedAdvisorUuid	String	UUID of the advisor to whom appointment will be assigned. Get from eligible advisors API	No
opCodes	Array	List of operation codes/services for the appointment	No
customerDetails	Object	Details of the customer and vehicle	Yes
transportOption	String	UUID of the transport option. Get from transport options API	No
note	String	Additional notes for the appointment	No
expiry	String	Expiry date-time for the draft appointment in yyyy-MM-ddTHH:mm:ss format	No

Explaining objects in request body

appointmentCommunicationPreference

Property Name	Value	Description	Required
emailConfirmation	Boolean	Whether to send email confirmation	No
emailReminder	Boolean	Whether to send email reminder	No
notifyCustomer	Boolean	Whether to notify customer about appointment	No
sendCommunicationToDA	Boolean	Whether to send communications to dealer associate	No
textConfirmation	Boolean	Whether to send text confirmation	No
textReminder	Boolean	Whether to send text reminder	No

Note: If you don't want any communication to be sent, you can omit this object or set all values to false.

opCodes

Property Name	Value	Description	Required
laborOpCode	String	Operation code for the service	No
description	String	Description of the service	No
opCodeName	String	Name of the opcode	No
operationUuid	String	Unique token assigned to an operation	No

Note: Operation codes can be obtained from the Opcodes API. At minimum, provide the laborOpCode.

customerDetails

Property Name	Value	Description	Required
uuid	String	Customer's UUID in myKaarma. Get from customer search API	Yes
vehicleIdentifiers	Object	Vehicle identification information	Yes

vehicleIdentifiers

Property Name	Value	Description	Required
uuid	String	Vehicle's UUID in myKaarma	No
vin	String	Vehicle Identification Number	No

Note: For vehicle identification, you can provide either the uuid or vin. At least one of these fields must be provided.

Sample Curl with VIN

curl --location 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/draftAppointment' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{basic_auth_token}}' \
--data '{
  "appointmentCommunicationPreference": {
    "emailConfirmation": true,
    "emailReminder": true,
    "notifyCustomer": true,
    "sendCommunicationToDA": true,
    "textConfirmation": true,
    "textReminder": true
  },
  "appointmentEndDateTime": "2024-01-01T10:00:00",
  "appointmentStartDateTime": "2024-01-01T09:00:00",
  "assignedAdvisorUuid": "{{advisor_uuid}}",
  "opCodes": [
    {
      "laborOpCode": "OIL_CHANGE",
      "description": "Oil Change Service",
      "opCodeName": "Oil Change"
    }
  ],
  "customerDetails": {
    "uuid": "{{customer_uuid}}",
    "vehicleIdentifiers": {
      "vin": "1HGCM82633A123456"
    }
  },
  "transportOption": "{{transport_option_uuid}}",
  "note": "Regular maintenance service",
  "expiry": "2024-02-01T00:00:00"
}'

Sample Curl with Vehicle UUID

curl --location 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/draftAppointment' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{basic_auth_token}}' \
--data '{
  "appointmentCommunicationPreference": {
    "emailConfirmation": true,
    "emailReminder": true,
    "notifyCustomer": true,
    "sendCommunicationToDA": true,
    "textConfirmation": true,
    "textReminder": true
  },
  "appointmentEndDateTime": "2024-01-01T10:00:00",
  "appointmentStartDateTime": "2024-01-01T09:00:00",
  "assignedAdvisorUuid": "{{advisor_uuid}}",
  "opCodes": [
    {
      "laborOpCode": "OIL_CHANGE",
      "description": "Oil Change Service",
      "opCodeName": "Oil Change"
    }
  ],
  "customerDetails": {
    "uuid": "{{customer_uuid}}",
    "vehicleIdentifiers": {
      "uuid": "{{vehicle_uuid}}",
      "vin": "{{vehicle_vin}}
    }
  },
  "transportOption": "{{transport_option_uuid}}",
  "note": "Regular maintenance service",
  "expiry": "2024-02-01T00:00:00"
}'

Response

{
  "statusCode": 0,
  "draftAppointmentUuid": "string",
  "shortUrl": "string",
  "error": {
    "errorCode": "string",
    "errorDescription": "string",
    "errorUID": "string"
  },
  "warnings": [
    {
      "warningCode": "string",
      "warningDescription": "string"
    }
  ]
}