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. You can also create a linked dropoff vehicle trip in the same request by adding dropTripInformation. 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
pickupTripInformation	Object	Details of the pickup trip event. On create, this must represent PICKUP_VEHICLE.	Yes
dropTripInformation	Object	Details of the linked dropoff vehicle trip event. Include this only when the appointment should be created with both pickup and dropoff trips.	No
appointmentInformation	Object	Details of the appointment to be created	Yes
vehicleInformation	Object	Details of the vehicle for which the appointment is created	No
requesterUserUUID	String	UUID of the user making the request. Passed to the downstream PnD service, which requires it whenever source is not WEB.	Conditional — required unless source is WEB
source	String	Platform source of the request. Possible values: DEALER_APP, WEB, PND_API, EXTERNAL_CONTROLLER. If WEB, some downstream validations such as assignedByDealerAssociateUUID are relaxed. No explicit default is applied by the partner create endpoint.	No
appointmentMetaData	Object	Meta data of the appointment	No
pickupDeliveryTripMetadata	Object	Metadata for pickup and delivery appointment handling, such as sub-transport option details. Trip UUIDs are returned in the response and are not sent here on create.	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.

pickupTripInformation

This object contains the pickup 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. For this partner create endpoint, the pickup trip must be PICKUP_VEHICLE. If omitted, the API defaults it to PICKUP_VEHICLE.	No
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
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

dropTripInformation

Include this object when you want to create a linked dropoff vehicle trip along with the pickup trip. It uses the same field structure as pickupTripInformation, with these differences:

Property Name	Value	Description	Required
rideType	String	Type of ride. For this partner create endpoint, the dropoff trip must be DROPOFF_VEHICLE. If omitted, the API defaults it to DROPOFF_VEHICLE.	No
rideTime	String	Scheduled time for the dropoff trip in ISO-8601 format with timezone offset. Required for dropoff ride types.	Yes, when dropTripInformation is present
mustStartBy	String	Latest start time for the dropoff trip in ISO-8601 format with timezone offset	No
originAddress	String	Dropoff origin address	No
originLocationLat	Double	Latitude of the dropoff origin	No
originLocationLon	Double	Longitude of the dropoff origin	No
optionalFields	Map<String, String>	Additional optional key-value pairs	No

The API links the created dropoff trip to the created pickup trip automatically. Do not send linkedTripUuids or parentEventUUID for normal partner create requests.

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
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
pickupEventUUID	String	Alias for eventUUID, returned for newer partner integrations
dropoffEventUUID	String	UUID of the created dropoff trip event, when dropTripInformation was provided
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 both appointmentInformation.creatorUser and requesterUserUUID. If you do not use source: "WEB" (or send source as null), you must provide both identity fields:

• appointmentInformation.creatorUser.uuid — checked upfront by the partner endpoint; missing → 400 VALID_CREATOR_USER_UUID_REQUIRED (also surfaces downstream as MISSING_ASSIGNED_BY_DEALER_ASSOCIATE_UUID if the partner gate is bypassed).
• requesterUserUUID at the top level — checked by the downstream PnD service; missing → 400 USER_TOKEN_IS_BLANK.

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",
  "pickupTripInformation": {
    "rideType": "PICKUP_VEHICLE"
  },
  "appointmentInformation": {
    "customerAppointmentPreference": {}
  }
}'

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

Minimal Curl With Dropoff

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",
  "pickupTripInformation": {
    "rideType": "PICKUP_VEHICLE",
    "mustStartBy": "2026-04-06T12:45:00-0700"
  },
  "dropTripInformation": {
    "rideType": "DROPOFF_VEHICLE",
    "rideTime": "2026-04-08T15:00:00-0700",
    "mustStartBy": "2026-04-08T14:45:00-0700"
  },
  "appointmentInformation": {
    "customerAppointmentPreference": {}
  }
}'

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",
  "requesterUserUUID": "80c9166f65eecad91e3855555svdgerfg3e5d7a95841c3a2a7086d1c87a",
  "source": "WEB",
  "locale": "en-US",
  "vehicleInformation": {
    "vehicleUuid": "kdFmlaWcUCWMAdZotP3fgdfVnOKHge56t0NXuG4QpXdWY",
    "vin": "VEHICLE_VIN",
    "vehicleKey": null,
    "vehicleYear": "2026",
    "vehicleMake": "Toyota",
    "vehicleModel": "Camry",
    "estimatedMileage": "25000"
  },
  "pickupTripInformation": {
    "rideType": "PICKUP_VEHICLE",
    "tripStatus": null,
    "loanerVehicleRequired": false,
    "isDropCar": false,
    "serviceAdvisorName": "Jane Smith",
    "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
  },
  "dropTripInformation": {
    "rideType": "DROPOFF_VEHICLE",
    "rideTime": "2026-04-06T17:00:00-0700",
    "mustStartBy": "2026-04-06T16:45:00-0700",
    "loanerVehicleRequired": false,
    "isDropCar": false,
    "originAddress": "456 Dealer Avenue, City, State 12345",
    "originLocationLat": 34.0622,
    "originLocationLon": -118.2537,
    "destinationAddress": "123 Customer Street, City, State 12345",
    "destLocationLat": 34.0522,
    "destLocationLon": -118.2437
  },
  "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",
  "pickupEventUUID": "abc12345-def6-7890-ghij-klmnopqrstuv",
  "dropoffEventUUID": "drop12345-def6-7890-ghij-klmnopqrstuv",
  "appointmentUUID": "xyz98765-uvw4-3210-abcd-efghijklmnop",
  "statusCode": 200,
  "errors": null,
  "warnings": null
}

Possible Errors

The create API can fail at the authentication layer, the partner request validation layer, the downstream pickup/delivery trip creation layer, or the downstream appointment creation layer.

Authentication and authorization errors

HTTP Status	Error Code	When it happens
401	UNAUTHORIZED	The Basic Auth credentials are missing or invalid.
403	FORBIDDEN	The client does not have the required appointment.create scope at the dealer level for the requested dealer.

Partner request validation errors

These are the explicit validation errors enforced by the partner create endpoint before the downstream trip and appointment flows run.

HTTP Status	Error Code	Error Description	When it happens
400	INVALID_DEALER_UUID	Invalid dealer UUID is provided in the request	dealerUuid path param is blank or invalid.
400	INVALID_DEPT_UUID	Invalid dealer department UUID is provided in the request	dealerDepartmentUUID is missing from the request body.
400	CUSTOMER_INFO_MISSING	minimum info required to match customer: (FirstName OR LastName) AND At least any one Customer Communication (phone/email) OR (FirstName AND LastName) OR VIN(FirstName OR LastName)	customerUUID is missing from the partner request.
400	PARTNER_APPOINTMENT_DATETIME_REQUIRED	appointmentDateTime is required in the partner appointment request	appointmentDateTime is missing.
400	INVALID_APPOINTMENT_INFORMATION	Invalid request. appointmentInformation is blank.	appointmentInformation is missing.
400	PARTNER_TRIP_INFORMATION_REQUIRED	pickupTripInformation is required in the partner appointment request	pickupTripInformation is missing.
400	PICKUP_AND_DELIVERY_TRANSPORT_OPTION_REQUIRED	Pickup and Delivery transport option is required when pickupTripInformation or dropTripInformation is present	appointmentInformation.transportOption is present but not set to PICKUP_AND_DELIVERY.
400	PICKUP_RIDE_TYPE_MUST_BE_PICKUP_VEHICLE	Pickup trip rideType must be PICKUP_VEHICLE	pickupTripInformation.rideType is sent with any non-pickup ride type.
400	DROPOFF_RIDE_TYPE_MUST_BE_DROPOFF_VEHICLE	Dropoff trip rideType must be DROPOFF_VEHICLE	dropTripInformation.rideType is sent with any non-dropoff ride type.
400	DROPOFF_RIDE_TIME_REQUIRED	dropTripInformation.rideTime is required for dropoff ride types	dropTripInformation is provided for a dropoff flow but rideTime is missing.
400	VALID_CREATOR_USER_UUID_REQUIRED	appointmentInformation.creatorUser.uuid is required when source is not WEB	source is not WEB (or is null) and appointmentInformation.creatorUser.uuid is missing or blank.
400	LOANER_AND_DROP_CAR_CANNOT_BOTH_BE_TRUE	loanerVehicleRequired and isDropCar cannot both be true	Either pickupTripInformation or dropTripInformation has both loanerVehicleRequired=true and isDropCar=true.
400	PRIMARY_AND_SECONDARY_DRIVER_CANNOT_BE_SAME	primaryDriverUUID and secondaryDriverUUID cannot be the same	Either pickupTripInformation or dropTripInformation has the same UUID set for primaryDriverUUID and secondaryDriverUUID.

Downstream pickup and delivery trip validation errors

After partner request validation passes, the API creates the pickup trip first. Common downstream trip validation failures include:

HTTP Status	Error Code	When it happens
400	INVALID_CREATE_EVENT_REQUEST	The transformed trip-create payload is invalid or incomplete.
400	MISSING_START_TIME	The pickup trip request does not contain a valid appointmentTime.
400	MISSING_ASSIGNED_BY_DEALER_ASSOCIATE_UUID	source is not WEB and appointmentInformation.creatorUser.uuid is missing. Typically caught upfront as VALID_CREATOR_USER_UUID_REQUIRED; surfaces here only if the partner-gate check is bypassed. Applies to the pickup-only flow (no dropTripInformation).
400	USER_TOKEN_IS_BLANK	source is not WEB (or is null) and the top-level requesterUserUUID is missing. The downstream PnD service requires requesterUserUUID for non-WEB sources on the with-dropoff flow (dropTripInformation present).
400	MISSING_DEALER_UUID	The downstream trip-create payload does not contain a dealer UUID.
400	DROP_CAR_AND_LOANER_REQUESTED_BOTH_CAN_NOT_TRUE	pickupTripInformation.loanerVehicleRequired=true and pickupTripInformation.isDropCar=true are both sent together. Typically caught upfront as LOANER_AND_DROP_CAR_CANNOT_BOTH_BE_TRUE; surfaces here only if the partner-gate check is bypassed.
4xx or 5xx	other pickup/delivery service error code	The trip service rejects the request or fails while creating the pickup or linked dropoff trip.

Downstream appointment creation errors

If trip creation succeeds but appointment creation fails, the response can still return errors populated from the downstream appointment service.

HTTP Status	Error Code	When it happens
4xx or 5xx	downstream appointment service error code	The appointment service rejects the transformed appointment payload or fails while creating the appointment.
500	INTERNAL_ERROR or INTERNAL_SERVER_ERROR	An unexpected server-side failure occurs while processing the request.

Error response example

{
  "eventUUID": null,
  "pickupEventUUID": null,
  "dropoffEventUUID": null,
  "appointmentUUID": null,
  "statusCode": 400,
  "errors": [
    {
      "errorCode": "PARTNER_TRIP_INFORMATION_REQUIRED",
      "errorDescription": "pickupTripInformation is required in the partner appointment request"
    }
  ],
  "warnings": null
}

Related APIs

• Get partner trips for an appointment
• Update a partner appointment with trip
• Delete a partner appointment with trip