How to create a partner appointment with trip

This document explains how to create an appointment along with a pickup and delivery (PnD) trip in a single API call using the Partner v2 endpoint. This endpoint provides a simplified, consolidated contract compared to the standard appointment-with-trip endpoint — trip and appointment details are merged into one flat request rather than two separate nested objects.

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/dealers/{dealerUuid}/partner-appointments-with-trip
      ?mobileServiceApptUuid={mobileServiceApptUuid}
      &regularServiceApptUuid={regularServiceApptUuid}

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 CreateAppointmentWithTripPartnerRequest object — a flat, consolidated contract that merges trip and appointment details into a single structure. Unlike the standard endpoint, there is no separate savePickupDeliveryTripEventRequest wrapper.

Note: The dealerUuid is sourced from the URL path only and must not be included in the request body.

Property Name	Value	Description	Required
customerUUID	String	Unique token assigned to each customer in myKaarma	Yes
appointmentDateTime	String	Preferred appointment date-time in ISO-8601 format with timezone offset (e.g., 2026-04-06T13:00:00-0700). The timezone is used for the trip; the time without timezone is used for the appointment.	Yes
dealerDepartmentUUID	String	UUID of the dealer department	Yes
tripInformation	Object	Details of the pickup and delivery trip event	Yes
appointmentInformation	Object	Details of the appointment to be created	Yes
vehicleInformation	Object	Details of the vehicle for which the appointment is created	No
dealerName	String	Display name of the dealer. Used in trip notification emails.	No
requesterUserUUID	String	UUID of the user making the request. Passed to the PnD service for validation.	No
source	String	Platform 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)
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 language preference (e.g., en-US, fr-CA)	No

appointmentDateTime

Important: The partner endpoint accepts a single appointmentDateTime with timezone at the top level (e.g., 2026-04-06T13:00:00-0700).

• The full value with timezone is used as appointmentTime for the trip.
• The timezone is stripped to derive appointmentStartDateTime for the appointment (e.g., 2026-04-06T13:00:00).
• appointmentEndDateTime is not accepted — it is automatically computed from the dealer's configured slot size.

This differs from the standard appointment-with-trip endpoint where you must provide appointmentStartDateTime (no timezone) inside appointmentInformation and appointmentTime (with timezone) inside the trip event separately.

tripInformation

This object contains the pickup and delivery trip details in a flat structure.

Note: serviceAdvisorUUID and assignedByDealerAssociateUUID are automatically derived from appointmentInformation.assignedUser and appointmentInformation.creatorUser respectively — you do not need to set them here.

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
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
loanerVehicleRequired	Boolean	Whether a loaner vehicle is required. Cannot be true simultaneously with isDropCar.	No
mustStartBy	String	Latest start time for the trip in ISO-8601 format with timezone offset	No
tripStatus	String	Status of the trip. If set to DRAFT or AUTO_DRAFT, customer messaging is suppressed.	No
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
serviceAdvisorName	String	Display name of the service advisor. The service advisor UUID is derived from appointmentInformation.assignedUser.	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
isDropCar	Boolean	Whether the customer is dropping off their car. 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
loanerModel	String	Model of the loaner vehicle (e.g., 2026 Camry)	No
roNumber	String	Repair order number associated with the trip	No
dealerOrderUUID	String	UUID of the dealer order	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
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

appointmentInformation

This object contains the core appointment details. Note that appointmentStartDateTime and appointmentEndDateTime are not part of this object in the partner endpoint — they are derived from the top-level appointmentDateTime field.

Property Name	Value	Description	Required
customerAppointmentPreference	Object	Preferences for customer communication. Must be provided (can be empty {}).	Yes
assignedUser	Object	Dealer associate to whom the appointment is assigned. Also drives the service advisor UUID on the trip.	No
creatorUser	Object	Dealer associate who created the appointment. Drives the trip's assignedByDealerAssociateUUID, which the PnD service validates downstream.	Conditional — required unless source is WEB
transportOption	Object	Transport option details	No
serviceList	List<Object>	List of services/opcodes for the appointment	No
appointmentKey	String	Unique token assigned to each appointment in DMS	No
mileageText	String	Vehicle mileage at time of appointment (in miles)	No
comments	String	Customer-facing notes for the appointment	No
internalNotes	String	Internal notes for dealership personnel only; not visible to customers	No
status	String	Status of the appointment. To create an appointment, send as null.	No
recall	Boolean	Whether the appointment includes a recall	No
pushToDms	Boolean	Whether the appointment should be pushed to DMS	No (defaults to true)
shouldAutoComputeSlot	Boolean	Whether to auto-compute slot if dates are not provided	No
skipBrandValidation	Boolean	Whether to skip vehicle make validation	No
isDiagnostic	Boolean	Whether this is a diagnostic appointment	No
errorOnDuplicate	Boolean	Whether to error if a duplicate appointment is found	No (defaults to false)
overrideExistingAppointment	Boolean	Whether to override an existing appointment	No (defaults to true)
draftUuid	String	UUID of a linked draft appointment	No
sdSessionId	String	Shift Digital analytics session ID	No

vehicleInformation

Property Name	Value	Description	Required
vehicleUuid	String	Unique identifier of vehicle in myKaarma	No
vin	String	Vehicle Identification Number — unique code used by the automotive industry to identify the vehicle	No
vehicleKey	String	Unique key of vehicle in the DMS	No
vehicleYear	String	Model year of the vehicle (e.g., 2026)	No
vehicleMake	String	Make of the vehicle (e.g., Toyota)	No
vehicleModel	String	Model of the vehicle (e.g., Camry)	No
estimatedMileage	String	Estimated mileage of the vehicle	No

Note

None of the fields in this object are required but if you want a vehicle to be associated with the appointment, please pass one of these fields. You will get the UUID of the vehicle in the same process of getting a customer.

• vehicleUuid — Recommended and fastest option; use when you have the myKaarma vehicle UUID from customer search
• vin — Supported but slightly slower as we need to search for the corresponding UUID
• vehicleKey — Use when you have the DMS vehicle key

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)

Note: This minimal payload uses "source": "WEB" to opt into the relaxed validation path, which allows omitting appointmentInformation.creatorUser. If you do not use source: "WEB", you must also provide appointmentInformation.creatorUser with a valid uuid — otherwise the PnD service rejects the request with MISSING_ASSIGNED_BY_DEALER_ASSOCIATE_UUID.

curl --location --request POST 'https://api.mykaarma.com/appointment/v2/dealers/{{dealer_uuid}}/partner-appointments-with-trip' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerUUID": "{{customer_uuid}}",
  "appointmentDateTime": "2026-04-06T13:00:00-0700",
  "dealerDepartmentUUID": "{{department_uuid}}",
  "source": "WEB",
  "tripInformation": {
    "rideType": "PICKUP_VEHICLE"
  },
  "appointmentInformation": {
    "customerAppointmentPreference": {}
  }
}'

# With optional query parameters:
# POST .../partner-appointments-with-trip?mobileServiceApptUuid={{mobile_appt_uuid}}&regularServiceApptUuid={{regular_appt_uuid}}

Complete Curl

curl --location --request POST 'https://api.mykaarma.com/appointment/v2/dealers/{{dealer_uuid}}/partner-appointments-with-trip?mobileServiceApptUuid={{mobile_appt_uuid}}&regularServiceApptUuid={{regular_appt_uuid}}' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerUUID": "fdgdfdfretertegbv43-A9ujPPd-M",
  "appointmentDateTime": "2026-04-06T13:00:00-0700",
  "dealerDepartmentUUID": "8ec821aefe98664ab15dfwrtrgfdghl0b1aeda9ff58df3db89bb0a55a3",
  "dealerName": "Example Motors",
  "requesterUserUUID": "80c9166f65eecad91e3855555svdgerfg3e5d7a95841c3a2a7086d1c87a",
  "source": "WEB",
  "locale": "en-US",
  "vehicleInformation": {
    "vehicleUuid": "kdFmlaWcUCWMAdZotP3fgdfVnOKHge56t0NXuG4QpXdWY",
    "vin": "VEHICLE_VIN",
    "vehicleKey": null,
    "vehicleYear": "2026",
    "vehicleMake": "Toyota",
    "vehicleModel": "Camry",
    "estimatedMileage": "25000"
  },
  "tripInformation": {
    "rideType": "PICKUP_VEHICLE",
    "tripStatus": null,
    "loanerVehicleRequired": false,
    "isDropCar": false,
    "serviceAdvisorName": "Jane Smith",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "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
  },
  "appointmentInformation": {
    "transportOption": {
      "altTransportation": null,
      "transportation": null,
      "transportOptionUuid": "dfsdsf43tfxs-pCn0VBtnCur1AsjPwkH2RHUpf89LiMU",
      "bookingID": null,
      "bookInThirdParty": false
    },
    "assignedUser": {
      "uuid": "6bed86cc14791jkbdsf85a396610a3a84737546a0dd4ed23f522f90c91fe0",
      "deptUUID": "8ec821aefe98664ab15dfwrtrgfdghl0b1aeda9ff58df3db89bb0a55a3",
      "teamUuid": null
    },
    "creatorUser": {
      "uuid": "80c9166f65eecad91e3855555svdgerfg3e5d7a95841c3a2a7086d1c87a",
      "deptUUID": "8ec821aefe9twr42f34f26c3c46f9c37d0b1aeda9ff58df3db89bb0a55a3",
      "teamUuid": null
    },
    "appointmentKey": null,
    "mileageText": null,
    "comments": "",
    "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,
        "operationType": "OPCODE",
        "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,
    "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
}