How to create an appointment with trip

This document explains how to create an appointment along with a pickup and delivery (PnD) trip in a single API call. This is useful when you want to schedule a service appointment and simultaneously set up a pickup/delivery trip for the customer's vehicle.

To create an appointment with trip, 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.

Request

HTTP request

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

Parameters

Path parameter:

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

Query parameters:

Parameter Name	Value	Description	Required
mobileServiceApptUuid	String	UUID of an existing mobile service appointment to delete after creating the new appointment with trip	No
regularServiceApptUuid	String	UUID of an existing regular service appointment to delete after creating the new appointment with trip	No

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

The request body is a SaveAppointmentWithTripRequest object containing two main parts:

Property Name	Value	Description	Required
savePickupDeliveryTripEventRequest	Object	Details of the pickup and delivery trip event to be created	Yes
createAppointmentWithTripRequest	Object	Details of the appointment to be created, including trip metadata	Yes

savePickupDeliveryTripEventRequest

Property Name	Value	Description	Required
pickupDeliveryTripEvent	Object	The pickup and delivery trip event details	Yes
requesterUserUUID	String	UUID of the user making the request. Passed as the user token to the PnD service for validation.	Yes
dealerDepartmentUUIDList	List<String>	List of dealer department UUIDs associated with this trip	Yes
source	String	Source of the request. Possible values: DEALER_APP, WEB, PND_API, EXTERNAL_CONTROLLER. If WEB, some validations (e.g., assignedByDealerAssociateUUID) are relaxed.	No (defaults to DEALER_APP)

pickupDeliveryTripEvent

This is the core trip event object. Below are the key fields:

Note: The sendMessageToCustomer and isValid fields are overridden by the system (forced to false) during trip creation regardless of what the caller sends. The trip is marked valid later during the SAR-Trip mapping step.

Property Name	Value	Description	Required
appointmentTime	String	The scheduled time for the trip. Format: yyyy-MM-dd'T'HH:mm:ssZ (ISO 8601 with timezone offset, e.g., 2024-10-25T11:15:00-0700). Validated by the PnD service.	Yes
rideType	String	Type of ride. Must be one of: PICKUP_CUSTOMER, PICKUP_VEHICLE, DROPOFF_CUSTOMER, DROPOFF_VEHICLE, LOANER_SWAP, MISCELLANEOUS, RIDE_SHARE. Validated by the PnD service.	Yes
dealerUUID	String	UUID of the dealer	Yes
dealerDepartmentUUID	String	UUID of the dealer department. Used for customer lookup and trip creation internally.	Yes
customerUUID	String	UUID of the customer for this trip. Required for all ride types except MISCELLANEOUS (where a system customer is used if absent).	Conditional
assignedByDealerAssociateUUID	String	UUID of the dealer associate who assigned the trip. Required unless source is WEB.	Conditional
customerFirstName	String	First name of the customer. Automatically set from customer data if not provided.	No
customerLastName	String	Last name of the customer. Automatically set from customer data if not provided.	No
vehicleIdentifiers	Object	Identifiers for the customer's vehicle	No
roNumber	String	Repair order number associated with the trip	No
dealerOrderUUID	String	UUID of the dealer order	No
originAddress	String	Pickup address for the trip	No
originLocationLat	Double	Latitude of the pickup location	No
originLocationLon	Double	Longitude of the pickup location	No
destinationAddress	String	Delivery address for the trip	No
destLocationLat	Double	Latitude of the delivery location	No
destLocationLon	Double	Longitude of the delivery location	No
loanerVehicleRequired	Boolean	Whether a loaner vehicle is required. Cannot be true simultaneously with isDropCar.	No
isDropCar	Boolean	Whether this is a drop car trip. Cannot be true simultaneously with loanerVehicleRequired.	No (defaults to false)
loanerVehicleUuid	String	UUID of the loaner vehicle. For LOANER_SWAP, cannot be the same as swappedLoanerVehicleUuid.	No
swappedLoanerVehicleUuid	String	UUID of the swapped loaner vehicle (for LOANER_SWAP ride type only)	No
loanerDescription	String	Description of the loaner vehicle	No
serviceAdvisorUUID	String	UUID of the service advisor	No
serviceAdvisorName	String	Name of the service advisor	No
primaryDriverUUID	String	UUID of the primary driver. For PICKUP_VEHICLE/DROPOFF_VEHICLE, cannot be blank if secondaryDriverUUID is present.	Conditional
secondaryDriverUUID	String	UUID of the secondary driver. Cannot be the same as primaryDriverUUID.	No
tripStatus	String	Status of the trip. If set to DRAFT or AUTO_DRAFT, customer messaging is suppressed.	No
linkedAppointmentUuid	String	UUID of a linked appointment	No
linkedTripUuids	List<String>	UUIDs of linked trips. Each must correspond to a valid existing trip.	No
subTrips	List<Object>	List of sub-trips associated with this trip event	No
optionalFields	Map<String, String>	Additional optional key-value pairs	No

createAppointmentWithTripRequest

This object extends the standard appointment request body. It contains all fields from the create appointment request along with additional trip metadata.

Property Name	Value	Description	Required
customerUuid	String	Unique token assigned to each customer in myKaarma	Yes
appointmentInformation	Object	Specific details of the appointment to be created	Yes
vehicleInformation	Object	Details of the vehicle for which appointment is to be created such as vin, vehicleKey, vehicleUuid	No
appointmentMetaData	Object	Meta data of the appointment	No
pickupDeliveryTripMetadata	Object	Meta data of the pickup and delivery trip. If not provided, automatically created by the system with the trip UUID.	No
locale	String	Customer's manually selected language (e.g., en-CA, fr-CA)	No

Note: The customerAppointmentPreference object inside appointmentInformation is required. The API accesses textConfirmation and emailConfirmation fields directly from this object.

Important: The appointment date-time format is different from the trip's appointmentTime format:

• Appointment: yyyy-MM-dd'T'HH:mm:ss (no timezone, e.g., 2024-10-25T11:15:00)
• Trip: yyyy-MM-dd'T'HH:mm:ssZ (with timezone offset, e.g., 2024-10-25T11:15:00-0700)

For details on vehicleInformation, appointmentInformation, and other standard appointment fields, please refer to the create appointment page.

Key appointmentInformation fields

Property Name	Value	Description	Required
appointmentStartDateTime	String	The preferred start date-time. Format: yyyy-MM-dd'T'HH:mm:ss (e.g., 2024-10-25T11:15:00). Strict parsing, no timezone.	Yes
appointmentEndDateTime	String	The preferred end date-time. Same format as start. If not provided, auto-computed from dealer configuration. Must be the same date as start.	No
customerAppointmentPreference	Object	Preferences for customer communication. Must be provided (can be empty {}).	Yes
assignedUser	Object	Dealer associate to whom the appointment is assigned. If not provided, system auto-assigns based on department configuration.	No
serviceList	List<Object>	List of services/opcodes for the appointment	No
transportOption	Object	Transport option details	No
comments	String	Customer-facing notes for the appointment	No
internalNotes	String	Internal notes for dealership personnel only	No
pushToDms	Boolean	Whether the appointment should be pushed to DMS	No (defaults to true)
recall	Boolean	Whether the appointment includes a recall	No

pickupDeliveryTripMetadata

Property Name	Value	Description	Required
tripUUID	String	Unique token assigned to a pickup and delivery trip in myKaarma. Automatically set by the system after trip creation.	No
subTransportOptionRequest	Object	Details of the sub transport option	No

subTransportOptionRequest

Property Name	Value	Description	Required
transportation	String	Name of transport option (e.g., Loaner)	No
transportOptionUuid	String	Unique token assigned to each transport option in myKaarma	No
altTransportation	String	Custom name for the transport option	No
bookingID	String	Third party booking ID. Only valid for Loaners	No
bookInThirdParty	Boolean	Indicator if booking was made in third party. Only valid for Loaners	No

Response

The response is a SaveAppointmentWithTripResponse object:

Property Name	Value	Description
eventUUID	String	UUID of the created pickup and delivery trip event
appointmentUUID	String	UUID of the created appointment
statusCode	Integer	HTTP status code of the response
errors	List<Object>	List of errors, if any
warnings	List<Object>	List of warnings, if any

Minimal Curl (required fields only)

curl --location --request POST 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/appointment-trip' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "savePickupDeliveryTripEventRequest": {
    "pickupDeliveryTripEvent": {
      "appointmentTime": "2024-10-25T11:15:00-0700",
      "rideType": "PICKUP_CUSTOMER",
      "dealerUUID": "{{dealer_uuid}}",
      "dealerDepartmentUUID": "{{department_uuid}}",
      "customerUUID": "{{customer_uuid}}"
    },
    "requesterUserUUID": "{{requester_uuid}}",
    "dealerDepartmentUUIDList": ["{{department_uuid}}"],
    "source": "WEB"
  },
  "createAppointmentWithTripRequest": {
    "customerUuid": "{{customer_uuid}}",
    "appointmentInformation": {
      "appointmentStartDateTime": "2024-10-25T11:15:00",
      "customerAppointmentPreference": {}
    }
  }
}'

Complete Curl

curl --location --request POST 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/appointment-trip' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "savePickupDeliveryTripEventRequest": {
    "pickupDeliveryTripEvent": {
      "appointmentTime": "2024-10-25T11:15:00-0700",
      "rideType": "PICKUP_CUSTOMER",
      "dealerUUID": "{{dealer_uuid}}",
      "dealerDepartmentUUID": "{{department_uuid}}",
      "customerUUID": "{{customer_uuid}}",
      "customerFirstName": "John",
      "customerLastName": "Doe",
      "assignedByDealerAssociateUUID": "{{da_uuid}}",
      "serviceAdvisorUUID": "{{advisor_uuid}}",
      "originAddress": "123 Customer Street, City, State 12345",
      "originLocationLat": 34.0522,
      "originLocationLon": -118.2437,
      "destinationAddress": "456 Dealer Avenue, City, State 12345",
      "destLocationLat": 34.0622,
      "destLocationLon": -118.2537,
      "loanerVehicleRequired": false,
      "isDropCar": false
    },
    "requesterUserUUID": "{{requester_uuid}}",
    "dealerDepartmentUUIDList": ["{{department_uuid}}"],
    "source": "WEB"
  },
  "createAppointmentWithTripRequest": {
    "customerUuid": "{{customer_uuid}}",
    "vehicleInformation": {
      "vehicleUuid": "{{vehicle_uuid}}"
    },
    "appointmentInformation": {
      "appointmentStartDateTime": "2024-10-25T11:15:00",
      "appointmentEndDateTime": "2024-10-25T11:29:59",
      "transportOption": {
        "transportOptionUuid": "{{transport_option_uuid}}"
      },
      "assignedUser": {
        "uuid": "{{advisor_uuid}}",
        "deptUUID": "{{department_uuid}}"
      },
      "comments": "",
      "internalNotes": "",
      "serviceList": [
        {
          "title": "{{labor_opcode}}",
          "operationUuid": "{{operation_uuid}}",
          "operationType": "OPCODE",
          "isCustomConcern": false
        }
      ],
      "customerAppointmentPreference": {
        "emailConfirmation": false,
        "textConfirmation": false,
        "emailReminder": false,
        "textReminder": false,
        "notifyCustomer": true,
        "sendCommunicationToDA": true
      },
      "status": null,
      "recall": false,
      "pushToDms": true
    },
    "pickupDeliveryTripMetadata": {
      "subTransportOptionRequest": {
        "transportOptionUuid": "{{transport_option_uuid}}"
      }
    }
  }
}'

Response Example

{
  "eventUUID": "abc12345-def6-7890-ghij-klmnopqrstuv",
  "appointmentUUID": "xyz98765-uvw4-3210-abcd-efghijklmnop",
  "statusCode": 200,
  "errors": null,
  "warnings": null
}