How to get partner trips for an appointment

This document explains how to fetch the pickup and linked dropoff trips for a partner appointment created through the Partner v2 appointment-with-trip endpoint.

Use this API before update or delete when you need the current pickup trip UUID and dropoff trip UUID for an appointment.

To get trips for an appointment, 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 credentials from us.

Request

HTTP request

GET  https://api.mykaarma.com/appointment/v2/dealers/{dealerUuid}/partner-appointments-with-trip/{sarUUID}/trips

Parameters

Path parameters

Parameter Name	Value	Description	Required
dealerUuid	String	Unique identifier of the dealer	Yes
sarUUID	String	UUID of the service appointment request whose pickup/dropoff trips should be fetched	Yes

Authorization

Scope	Level	Description
appointment.trip.read	Dealer	Authorises client to read trip details for appointments at the provided dealer

Behavior

• The API looks up the pickup trip mapped to the appointment.
• If a linked dropoff exists for that pickup, the response includes both trips.
• Use the pickup trip's eventUuid as pickupTripInformation.eventUUID in partner update requests.
• Use the dropoff trip's eventUuid as dropTripInformation.eventUUID in partner update requests.
• For partner delete requests, use the appointment UUID in the delete path. The delete API resolves the mapped pickup trip and any linked dropoff trip(s) internally.

Response

The response is a PickupDeliveryTripViewDtoResponse object:

Property Name	Value	Description
totalCount	Integer	Total number of trips returned
tripViewDtos	List<Object>	Pickup and linked dropoff trip details
statusCode	Integer	HTTP status code of the response
error	Object	Error details, if any
warnings	List<Object>	List of warnings, if any

tripViewDtos

Each trip object contains these key fields:

Property Name	Value	Description
eventUuid	String	UUID of the trip event
appointmentTime	String	Appointment time associated with the trip
rideTime	String	Scheduled ride time, used by dropoff ride types
mustStartBy	String	Latest time by which the trip must start
rideType	String	Trip ride type, such as PICKUP_VEHICLE or DROPOFF_VEHICLE
tripStatus	String	Current status of the trip
isValid	Boolean	Whether the trip is valid
linkedAppointmentUuid	String	UUID of the linked appointment
linkedTripUuids	List<String>	UUIDs of trips linked to this trip
customer	Object	Customer details
vehicle	Object	Vehicle details
serviceAdvisor	Object	Service advisor details
optionalFields	Map<String, String>	Additional optional key-value pairs

Curl Example

curl --location --request GET 'https://api.mykaarma.com/appointment/v2/dealers/{{dealer_uuid}}/partner-appointments-with-trip/{{sar_uuid}}/trips' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json'

Response Example

{
  "totalCount": 2,
  "tripViewDtos": [
    {
      "eventUuid": "{{pickup_trip_uuid}}",
      "appointmentTime": "2026-06-03T11:00:00-0700",
      "rideType": "PICKUP_VEHICLE",
      "tripStatus": "UNASSIGNED",
      "isValid": true,
      "linkedAppointmentUuid": "{{sar_uuid}}",
      "linkedTripUuids": [
        "{{dropoff_trip_uuid}}"
      ]
    },
    {
      "eventUuid": "{{dropoff_trip_uuid}}",
      "rideTime": "2026-06-06T15:00:00-0700",
      "rideType": "DROPOFF_VEHICLE",
      "tripStatus": "UNASSIGNED",
      "isValid": true,
      "linkedAppointmentUuid": "{{sar_uuid}}",
      "linkedTripUuids": [
        "{{pickup_trip_uuid}}"
      ]
    }
  ],
  "statusCode": 200,
  "error": null,
  "warnings": null
}

Possible Errors

The get-trips API can fail at the authentication layer, the request validation layer, or while resolving the mapped pickup/dropoff trips downstream.

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.trip.read scope at the dealer level for the requested dealer.

Request validation errors

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_SAR_UUID	Invalid SAR UUID is provided in the request	sarUUID path param is blank.
400	INVALID_DEPT_UUID	Invalid dealer department UUID is provided in the request	The API cannot derive a service department from the provided dealer UUID.

Trip lookup outcomes

HTTP Status	Error Code	When it happens
200 with null or no trip data	none	The appointment does not currently have an active mapped pickup trip, so there is nothing to return.
500	INTERNAL_SERVER_ERROR	An unexpected server-side error occurs while resolving the appointment-to-trip mapping or fetching the pickup/dropoff trips downstream.

Error response example

{
  "totalCount": 0,
  "tripViewDtos": null,
  "statusCode": 400,
  "error": {
    "errorCode": "INVALID_SAR_UUID",
    "errorDescription": "Invalid SAR UUID is provided in the request"
  },
  "warnings": null
}

Related APIs

• Create a partner appointment with trip
• Update a partner appointment with trip
• Delete a partner appointment with trip