How to get trips for an appointment

This document explains how to fetch pickup and delivery (PnD) trips linked to an appointment. This is useful when you want to view the trip details associated with a specific service appointment.

Request

HTTP request

PATCH  https://api.mykaarma.com/appointment/v2/dealer/{dealerUuid}/trips

Parameters

Path parameter:

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

Authorization

This request requires the following authorization scopes:

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

Request Body

Property Name	Value	Description	Required
sarUuid	String	UUID of the service appointment request (appointment) for which to fetch linked trips. Validated as non-blank.	Yes

Response

The response is a PickupDeliveryTripViewDtoResponse object:

Property Name	Value	Description
totalCount	Integer	Total number of trips linked to the appointment
tripViewDtos	List<Object>	List of trip view 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 view object contains the following key fields:

Property Name	Value	Description
eventUuid	String	Unique identifier for the trip event
version	Long	Version number of the trip
appointmentTime	String	Scheduled time for the trip
mustStartBy	String	Latest time by which the trip must start
rideType	String	Type of ride. Possible values: PICKUP_CUSTOMER, PICKUP_VEHICLE, DROPOFF_CUSTOMER, DROPOFF_VEHICLE, LOANER_SWAP, MISCELLANEOUS, RIDE_SHARE
tripStatus	String	Current status of the trip
parentEventUuid	String	UUID of the parent trip event, if this is a sub-trip
subTrips	List<Object>	List of sub-trips
internalRideType	String	Internal classification of the ride type
customer	Object	Customer details including name and contact information
vehicle	Object	Vehicle details
dealerOrder	Object	Dealer order details
department	Object	Department details
loaner	Object	Loaner vehicle details, if applicable
serviceAdvisor	Object	Service advisor details
primaryDriver	Object	Primary driver details
secondaryDriver	Object	Secondary driver details
assignedBy	Object	Details of who assigned the trip
updatedBy	Object	Details of who last updated the trip
isValid	Boolean	Whether the trip is valid
createdDate	String	Date when the trip was created
linkedAppointmentUuid	String	UUID of the linked appointment
linkedTripUuids	List<String>	UUIDs of other linked trips
optionalFields	Map<String, String>	Additional optional key-value pairs

Curl Example

curl --location --request PATCH 'https://api.mykaarma.com/appointment/v2/dealer/{{dealer_uuid}}/trips' \
--header 'Authorization: Basic {{basic_auth_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "sarUuid": "{{appointment_uuid}}"
}'

Response Example

{
  "totalCount": 1,
  "tripViewDtos": [
    {
      "eventUuid": "abc12345-def6-7890-ghij-klmnopqrstuv",
      "appointmentTime": "2024-10-25T11:15:00",
      "rideType": "PICKUP_CUSTOMER",
      "tripStatus": "SCHEDULED",
      "customer": {
        "firstName": "John",
        "lastName": "Doe"
      },
      "vehicle": {
        "vin": "1HGBH41JXMN109186"
      },
      "serviceAdvisor": {
        "uuid": "xyz98765-uvw4-3210-abcd-efghijklmnop",
        "firstName": "Jane",
        "lastName": "Smith"
      },
      "isValid": true,
      "linkedAppointmentUuid": "appt12345-def6-7890-ghij-klmnopqrstuv"
    }
  ],
  "statusCode": 200,
  "error": null,
  "warnings": null
}