How to update an appointment with trip

This document explains how to update an existing appointment along with its associated pickup and delivery (PnD) trip in a single API call. This is useful when you need to modify both the appointment details and the trip details simultaneously.

Request

HTTP request

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

Parameters

Path parameter:

Parameter Name	Value	Description	Required
dealerUuid	String	Unique identifier of dealer	Yes
sarUUID	String	Unique identifier of the service appointment request (appointment) to update	Yes

Query parameters:

Parameter Name	Value	Description	Required
enforcePreferences	Boolean	Whether to enforce preferences configured for each dealer in myKaarma	No

Authorization

This request requires the following authorization scopes:

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

Request Body

The request body is an UpdateAppointmentWithTripRequest object containing two main parts:

Property Name	Value	Description	Required
updatePickupDeliveryTripEventRequest	Object	Details of the updated pickup and delivery trip event	Yes
updateAppointmentForTripRequest	Object	Details of the appointment update, including trip metadata	Yes

Update Scenarios

The API supports three distinct scenarios based on the combination of pickupDeliveryTripEvent (in updatePickupDeliveryTripEventRequest) and tripUUID (in updateAppointmentForTripRequest.pickupDeliveryTripMetadata):

Scenario	pickupDeliveryTripEvent	tripUUID	Behavior
Update existing trip	Provided (not null)	Provided (not null)	Updates both the trip and the appointment
Create new trip	Provided (not null)	null or absent	Creates a new trip and links it to the appointment. Fails if a trip already exists.
Delete existing trip	null	Provided (not null)	Deletes the existing trip and updates the appointment

Important: Both pickupDeliveryTripEvent and tripUUID cannot be null at the same time — this will cause an error.

updatePickupDeliveryTripEventRequest

Property Name	Value	Description	Required
pickupDeliveryTripEvent	Object	The updated pickup and delivery trip event details. Set to null to trigger the delete trip scenario.	Conditional
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	No

pickupDeliveryTripEvent (for update/create scenarios)

When updating or creating a trip, include the trip event details. For the update scenario, the eventUUID field is required. For the create scenario, the fields follow the same requirements as the create appointment with trip page.

Note: For the update scenario, the PnD service validates that the trip exists in the database and that isValid is true.

Property Name	Value	Description	Required
eventUUID	String	UUID of the existing trip event. Required for the update scenario. Not needed for create.	Conditional
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).	Yes
rideType	String	Type of ride. Must be one of: PICKUP_CUSTOMER, PICKUP_VEHICLE, DROPOFF_CUSTOMER, DROPOFF_VEHICLE, LOANER_SWAP, MISCELLANEOUS, RIDE_SHARE.	Yes
customerUUID	String	UUID of the customer. Required for all ride types except MISCELLANEOUS.	Conditional
dealerUUID	String	UUID of the dealer	Yes
dealerDepartmentUUID	String	UUID of the dealer department	Yes
assignedByDealerAssociateUUID	String	UUID of the dealer associate who assigned the trip. Required unless source is WEB.	Conditional
customerFirstName	String	First name of the customer. Auto-populated from customer data if not provided.	No
customerLastName	String	Last name of the customer. Auto-populated 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

updateAppointmentForTripRequest

Property Name	Value	Description	Required
appointmentInformation	Object	Updated appointment details	Yes
customerAppointmentPreference	Object	Updated communication preferences for the customer	No
serviceList	List<Object>	Updated list of services/opcodes for the appointment	No
vehicleInformation	Object	Updated vehicle details	No
updatedByUserDetails	Object	Details of the user making the update	No
pickupDeliveryTripMetadata	Object	Meta data of the pickup and delivery trip containing trip and transport option information	Yes

appointmentInformation

Important: The update endpoint uses separate date and time fields, which is different from the create endpoint's combined appointmentStartDateTime format. The system concatenates appointmentDate + "T" + appointmentStartTime internally to produce the yyyy-MM-dd'T'HH:mm:ss format.

Property Name	Value	Description	Required
appointmentDate	String	Updated appointment date. Format: yyyy-MM-dd (e.g., 2024-10-26).	Yes
appointmentStartTime	String	Updated appointment start time. Format: HH:mm:ss (e.g., 10:00:00).	Yes
appointmentEndTime	String	Updated appointment end time. Format: HH:mm:ss (e.g., 10:29:59). If not provided, auto-computed from dealer configuration.	No
userUuid	String	UUID of the assigned user/advisor	No
comments	String	Updated comments for the appointment	No
internalNotes	String	Updated internal notes for dealership personnel only	No
altTransportation	String	Updated alternate transportation option	No
source	String	Source of the update	No

updatedByUserDetails

Property Name	Value	Description	Required
uuid	String	Unique token assigned to the user making the update	No
deptUUID	String	Unique token assigned to the department of the user	No
teamUuid	String	Unique token assigned to the team the user belongs to	No

customerAppointmentPreference

Property Name	Value	Description	Required
emailConfirmation	Boolean	Whether to send an email for appointment confirmation	No
textConfirmation	Boolean	Whether to send a text for appointment confirmation	No
emailReminder	Boolean	Whether to send a reminder email for the appointment	No
textReminder	Boolean	Whether to send a reminder text for the appointment	No
notifyCustomer	Boolean	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 where appointment confirmation email should be sent	No
confirmationPhoneNumber	String	Phone number where appointment confirmation text should be sent	No

pickupDeliveryTripMetadata

Property Name	Value	Description	Required
tripUUID	String	Unique token assigned to a pickup and delivery trip in myKaarma. Set to null to trigger the create trip scenario; provide an existing UUID for update or delete trip scenarios.	Conditional
subTransportOptionRequest	Object	Details of the sub transport option	No

For details on serviceList, vehicleInformation, and subTransportOptionRequest, please refer to the create appointment with trip page and the create appointment page.

Response

The response is a SaveAppointmentWithTripResponse object (same as create):

Property Name	Value	Description
eventUUID	String	UUID of the updated pickup and delivery trip event
appointmentUUID	String	UUID of the updated 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 (update scenario, required fields only)

curl --location --request POST 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/sar/{{sar_uuid}}/appointment-trip' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "updatePickupDeliveryTripEventRequest": {
    "pickupDeliveryTripEvent": {
      "eventUUID": "{{event_uuid}}",
      "appointmentTime": "2024-10-26T10:00:00-0700",
      "rideType": "PICKUP_CUSTOMER",
      "dealerUUID": "{{dealer_uuid}}",
      "dealerDepartmentUUID": "{{department_uuid}}",
      "customerUUID": "{{customer_uuid}}"
    },
    "requesterUserUUID": "{{requester_uuid}}",
    "dealerDepartmentUUIDList": ["{{department_uuid}}"],
    "source": "WEB"
  },
  "updateAppointmentForTripRequest": {
    "appointmentInformation": {
      "appointmentDate": "2024-10-26",
      "appointmentStartTime": "10:00:00"
    },
    "pickupDeliveryTripMetadata": {
      "tripUUID": "{{trip_uuid}}"
    }
  }
}'

Complete Curl

curl --location --request POST 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/sar/{{sar_uuid}}/appointment-trip' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "updatePickupDeliveryTripEventRequest": {
    "pickupDeliveryTripEvent": {
      "eventUUID": "{{event_uuid}}",
      "appointmentTime": "2024-10-26T10:00:00-0700",
      "rideType": "PICKUP_CUSTOMER",
      "dealerUUID": "{{dealer_uuid}}",
      "dealerDepartmentUUID": "{{department_uuid}}",
      "customerUUID": "{{customer_uuid}}",
      "assignedByDealerAssociateUUID": "{{da_uuid}}",
      "originAddress": "789 New Address, City, State 12345",
      "originLocationLat": 34.0522,
      "originLocationLon": -118.2437,
      "destinationAddress": "456 Dealer Avenue, City, State 12345",
      "destLocationLat": 34.0622,
      "destLocationLon": -118.2537,
      "serviceAdvisorUUID": "{{advisor_uuid}}"
    },
    "requesterUserUUID": "{{requester_uuid}}",
    "dealerDepartmentUUIDList": ["{{department_uuid}}"],
    "source": "WEB"
  },
  "updateAppointmentForTripRequest": {
    "appointmentInformation": {
      "appointmentDate": "2024-10-26",
      "appointmentStartTime": "10:00:00",
      "appointmentEndTime": "10:29:59",
      "userUuid": "{{advisor_uuid}}",
      "comments": "",
      "internalNotes": ""
    },
    "vehicleInformation": {
      "vehicleUuid": "{{vehicle_uuid}}"
    },
    "customerAppointmentPreference": {
      "emailConfirmation": false,
      "textConfirmation": false,
      "emailReminder": false,
      "textReminder": false,
      "notifyCustomer": true,
      "sendCommunicationToDA": true
    },
    "serviceList": [
      {
        "title": "{{labor_opcode}}",
        "operationUuid": "{{operation_uuid}}",
        "operationType": "OPCODE",
        "isCustomConcern": false
      }
    ],
    "updatedByUserDetails": {
      "uuid": "{{updater_uuid}}",
      "deptUUID": "{{department_uuid}}"
    },
    "pickupDeliveryTripMetadata": {
      "tripUUID": "{{trip_uuid}}",
      "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
}