How to filter trips

This document is designed to help you understand how you can filter trips based on certain parameters.

To get filtered trips list based on certain parameters, 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.

Note: Sub trips are the individual legs that make up a complete trip. A trip typically consists of two sub trips:

OUTBOUND: The leg from the dealership (origin) to the customer/vehicle location (destination)
INBOUND: The leg from the customer/vehicle location back to the dealership

Each sub trip can have its own driver assignment, status, transport type, and can be tracked independently. This allows for granular tracking of each leg of the journey, which is especially useful for trips that involve round-trip travel.

Request

HTTP request

POST https://api.mykaarma.com/pickupdelivery/v3/trip-view/list

Parameters

Request body:

Parameter Name	Type	Description	Required
`dealerDepartmentUUIDList`	`List<String>`	List of UUIDs of the dealer departments you want to fetch trips list for	Yes
`sortOrder`	`String`	Sort order for results. Possible values: "APPT_TIME_ASC", "APPT_TIME_DESC"	Yes
`dealerUuids`	`List<String>`	List of UUIDs of the dealers you want to filter trips list for	No
`eventUuids`	`List<String>`	List of UUIDs of specific events/trips you want to fetch	No
`startApptTime`	`String`	Start of appointment time range in which to filter trips. Format: "2023-01-01T00:00:00+0530"	No
`endApptTime`	`String`	End of appointment time range in which to filter trips. Format: "2023-01-10T00:00:00+0530"	No
`driverUuids`	`List<String>`	List of UUIDs of drivers (dealerAssociateUuid) to filter trips by	No
`customerUuids`	`List<String>`	List of UUIDs of customers to filter trips by	No
`tripStatuses`	`List<String>`	List of trip statuses to filter by. Possible values: "DRAFT", "AUTO_DRAFT", "ASSIGNED", "UNASSIGNED", "OUTBOUND", "INBOUND", "READY_TO_DRIVE", "AT_DESTINATION", "AT_DEALERSHIP", "COMPLETED", "CANCELLED"	No
`subTripStatuses`	`List<String>`	List of sub-trip statuses to filter by. Possible values: "DRAFT", "AUTO_DRAFT", "ASSIGNED", "UNASSIGNED", "READY_TO_DRIVE", "STARTED", "IN_PROGRESS", "AT_DEALERSHIP", "COMPLETED", "CANCELLED"	No
`rideTypes`	`List<String>`	List of ride types to filter by. Possible values: "PICKUP_CUSTOMER", "PICKUP_VEHICLE", "DROPOFF_CUSTOMER", "DROPOFF_VEHICLE", "LOANER_SWAP", "MISCELLANEOUS"	No
`docStatuses`	`List<String>`	List of document statuses to filter by. Possible values: "UPLOAD_PENDING", "VERIFICATION_PENDING", "VERIFIED", "REQUEST_ITEMS", "VERIFY_ITEMS", "PREVIEW_ITEMS"	No
`lastItemIndex`	`Integer`	Integer index of the last item from previous page (for pagination)	No
`pageNumber`	`Integer`	Page number for pagination (1-based)	No
`pageSize`	`Integer`	Number of items per page	No

Validation Rules:

Pagination vs Specific Event Filtering:
- You cannot use pagination (pageSize) together with specific event filtering (eventUuids non-empty).
- If pageSize is provided, then eventUuids must be empty/null.
- If eventUuids (non-empty) is provided, then pageSize must be null.
Time Range Validation:
- startApptTime and endApptTime must be both present or both absent (cannot have one without the other).
Pagination Parameters:
- When pageSize is provided, exactly one of pageNumber or lastItemIndex must be provided (not both, not neither).
Date Format Validation:
- When provided, startApptTime and endApptTime must be valid ISO 8601 formatted date-time strings.
DealerUuid Validation
- If eventUuids is not provided, dealerUuids must be non-empty.

Authorization

This request requires the following authorization scopes:

Scope	Level	Description
`pickupdelivery.trip.fetch`	`Department`	Authorises client to fetch trips for a department

Endpoint

curl -X POST "https://api.mykaarma.com/pickupdelivery/v3/trip-view/list"
-H "Content-Type: application/json"
-H "Authorization: {{basic_auth_token}}"
-d '{
  "requesterUserUUID": "{{requesterUserUUID}}",
  "dealerDepartmentUUIDList": [
    "{{dealerDepartmentUUID}}"
  ],
  "dealerUuids": [
    "{{dealerUuid}}"
  ],
  "eventUuids": [],
  "startApptTime": "{{startApptTime}}",
  "endApptTime": "{{endApptTime}}",
  "driverUuids": [],
  "customerUuids": [],
  "tripStatuses": [],
  "subTripStatuses": [],
  "rideTypes": [
    "{{rideType}}"
  ],
  "docStatuses": [],
  "lastItemIndex": null,
  "pageNumber": null,
  "pageSize": null,
  "sortOrder": "APPT_TIME_DESC"
}'

Response

{
  "statusCode": 0,
  "error": {
    "errorCode": "string",
    "errorDescription": "string",
    "metadata": "string"
  },
  "warnings": [
    {
      "warningCode": "string",
      "warningDescription": "string"
    }
  ],
  "totalCount": 0,
  "tripViewDtos": [
    {
      "eventUuid": "string",
      "version": 0,
      "appointmentTime": "string",
      "mustStartBy": "string",
      "rideType": "string",
      "tripStatus": "string",
      "parentEventUuid": "string",
      "subTrips": [
        {
          "subTripUuid": "string",
          "status": "string",
          "transportType": "string",
          "rideType": "string",
          "driver": {
            "uuid": "string",
            "firstName": "string",
            "lastName": "string",
            "roleName": "string",
            "departmentUuid": "string",
            "userUuid": "string"
          },
          "origin": {
            "address": "string",
            "latitudeDouble": 0.0,
            "longitude": 0.0
          },
          "destination": {
            "address": "string",
            "latitudeDouble": 0.0,
            "longitude": 0.0
          },
          "distanceInMiles": 0.0,
          "timeInMinutes": 0.0
        }
      ],
      "internalRideType": "string",
      "optionalFields": {},
      "customer": {
        "uuid": "string",
        "firstName": "string",
        "lastName": "string",
        "signatureUrl": "string",
        "dlVerified": false,
        "insuranceVerified": false
      },
      "vehicle": {
        "uuid": "string",
        "vin": "string",
        "year": "string",
        "make": "string",
        "model": "string",
        "estimatedMileage": "string",
        "inspectionUuid": "string",
        "inspectionByDaUuid": "string"
      },
      "dealerOrder": {
        "uuid": "string",
        "orderNumber": "string",
        "serviceAdvisor": {
          "uuid": "string",
          "firstName": "string",
          "lastName": "string",
          "roleName": "string",
          "departmentUuid": "string",
          "userUuid": "string"
        }
      },
      "department": {
        "uuid": "string",
        "name": "string",
        "dealer": {
          "uuid": "string",
          "name": "string"
        }
      },
      "loaner": {
        "uuid": "string",
        "description": "string",
        "model": "string",
        "isDropCar": false,
        "isLoanerRequested": false,
        "inspectionUuid": "string",
        "inspectionByDaUuid": "string",
        "bookingStatus": "string"
      },
      "swappedLoaner": {
        "uuid": "string",
        "description": "string",
        "model": "string",
        "isDropCar": false,
        "isLoanerRequested": false,
        "inspectionUuid": "string",
        "inspectionByDaUuid": "string",
        "bookingStatus": "string"
      },
      "assignedBy": {
        "uuid": "string",
        "firstName": "string",
        "lastName": "string",
        "roleName": "string",
        "departmentUuid": "string",
        "userUuid": "string"
      },
      "updatedBy": {
        "uuid": "string",
        "firstName": "string",
        "lastName": "string",
        "roleName": "string",
        "departmentUuid": "string",
        "userUuid": "string"
      },
      "serviceAdvisor": {
        "uuid": "string",
        "firstName": "string",
        "lastName": "string",
        "roleName": "string",
        "departmentUuid": "string",
        "userUuid": "string"
      },
      "primaryDriver": {
        "uuid": "string",
        "firstName": "string",
        "lastName": "string",
        "roleName": "string",
        "departmentUuid": "string",
        "userUuid": "string"
      },
      "secondaryDriver": {
        "uuid": "string",
        "firstName": "string",
        "lastName": "string",
        "roleName": "string",
        "departmentUuid": "string",
        "userUuid": "string"
      },
      "isValid": false,
      "createdDate": "string",
      "driverPayments": [
        {
          "driverUuid": "string",
          "dollarPerMinute": 0.0,
          "amountForMinutes": 0.0,
          "dollarPerMile": 0.0,
          "amountForMiles": 0.0,
          "dollarPerTrip": 0.0,
          "amountForTrip": 0.0,
          "totalAmount": 0.0,
          "salariedTotal": 0.0,
          "tripDetails": {
            "startTime": "string",
            "startDrivingTime": "string",
            "outboundCompleteTime": "string",
            "inboundStartTime": "string",
            "endDrivingTime": "string",
            "endTime": "string",
            "totalTimeInMinutes": 0,
            "distanceTravelledInMiles": 0.0,
            "maxSpeed": 0.0
          }
        }
      ],
      "docStatus": "string",
      "customerProfileToken": "string",
      "linkedAppointmentUuid": "string",
      "linkedTripUuids": []
    }
  ]
}

Example

Example Request

curl -L 'https://api.mykaarma.com/pickupdelivery/v3/trip-view/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic {{basic_auth_token}}' \
-d '{
  "dealerDepartmentUUIDList": ["a64b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8"],
  "dealerUuids": ["c86d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1"],
  "sortOrder": "APPT_TIME_ASC",
  "pageSize": 10,
  "lastItemIndex": 0,
  "startApptTime": "2025-10-31T00:00:00+0530",
  "endApptTime": "2025-10-31T23:59:59+0530",
  "tripStatuses": ["ASSIGNED","AT_DEALERSHIP","AT_DESTINATION","AUTO_DRAFT","CANCELLED","COMPLETED","DRAFT","INBOUND","OUTBOUND","READY_TO_DRIVE","UNASSIGNED"],
  "rideTypes": ["PICKUP_CUSTOMER","PICKUP_VEHICLE","DROPOFF_CUSTOMER","DROPOFF_VEHICLE","LOANER_SWAP","MISCELLANEOUS"]
}'

Example Response

{
  "statusCode": 200,
  "error": null,
  "warnings": null,
  "totalCount": 32,
  "tripViewDtos": [
    {
      "eventUuid": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
      "version": 2,
      "appointmentTime": "2025-10-30T11:30:27-0700",
      "mustStartBy": "2025-10-30T20:06:34-0700",
      "rideType": "PICKUP_VEHICLE",
      "tripStatus": "COMPLETED",
      "parentEventUuid": null,
      "subTrips": [
        {
          "subTripUuid": "xyz789abc123def456ghi012jkl345mno678pqr901stu234vwx",
          "status": "COMPLETED",
          "transportType": "THIRD_PARTY_VEHICLE",
          "rideType": "OUTBOUND",
          "driver": {
            "uuid": "d97e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2",
            "firstName": "John",
            "lastName": "Smith",
            "roleName": "Driver",
            "departmentUuid": "a64b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
            "userUuid": "e08f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3"
          },
          "origin": {
            "address": "123 Main Street, Suite 100, City, ST 12345, USA",
            "latitudeDouble": 33.7689325,
            "longitude": -118.1930229
          },
          "destination": {
            "address": "456 Oak Avenue, City, ST 12345, USA",
            "latitudeDouble": 45.6280277,
            "longitude": -122.673865
          },
          "distanceInMiles": 994.05,
          "timeInMinutes": 908.85
        },
        {
          "subTripUuid": "mno678pqr901stu234vwx567abc890def123ghi456jkl012",
          "status": "COMPLETED",
          "transportType": "CUSTOMER_VEHICLE",
          "rideType": "INBOUND",
          "driver": {
            "uuid": "d97e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2",
            "firstName": "John",
            "lastName": "Smith",
            "roleName": "Driver",
            "departmentUuid": "a64b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
            "userUuid": "e08f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3"
          },
          "origin": {
            "address": "456 Oak Avenue, City, ST 12345, USA",
            "latitudeDouble": 45.6280277,
            "longitude": -122.673865
          },
          "destination": {
            "address": "123 Main Street, Suite 100, City, ST 12345, USA",
            "latitudeDouble": 33.7689325,
            "longitude": -118.1930229
          },
          "distanceInMiles": 994.05,
          "timeInMinutes": 908.85
        }
      ],
      "internalRideType": "PICKUP_VEHICLE_NO_LOANER",
      "optionalFields": {},
      "customer": {
        "uuid": "f19a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4",
        "firstName": "Jane",
        "lastName": "Doe",
        "signatureUrl": "https://transportation-files.mykaarma.com/example123/pdoSign/2025/10/30/pdoSign_example.jpg",
        "dlVerified": false,
        "insuranceVerified": false
      },
      "vehicle": {
        "uuid": null,
        "vin": null,
        "year": null,
        "make": null,
        "model": null,
        "estimatedMileage": null,
        "inspectionUuid": "abc123def456ghi789jkl012",
        "inspectionByDaUuid": "d97e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
      },
      "dealerOrder": {
        "uuid": "a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
        "orderNumber": "RO-12345",
        "serviceAdvisor": null
      },
      "department": {
        "uuid": "a64b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
        "name": "Service",
        "dealer": {
          "uuid": "c86d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1",
          "name": "Sample Dealership"
        }
      },
      "loaner": {
        "uuid": null,
        "description": null,
        "model": null,
        "isDropCar": false,
        "isLoanerRequested": false,
        "inspectionUuid": null,
        "inspectionByDaUuid": null,
        "bookingStatus": null
      },
      "swappedLoaner": {
        "uuid": null,
        "description": null,
        "model": null,
        "isDropCar": null,
        "isLoanerRequested": false,
        "inspectionUuid": null,
        "inspectionByDaUuid": null,
        "bookingStatus": null
      },
      "assignedBy": {
        "uuid": "b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6",
        "firstName": "Service",
        "lastName": "Advisor",
        "roleName": "Service Advisor",
        "departmentUuid": "a64b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
        "userUuid": "c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7"
      },
      "updatedBy": {
        "uuid": "b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6",
        "firstName": "Service",
        "lastName": "Advisor",
        "roleName": "Service Advisor",
        "departmentUuid": "a64b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
        "userUuid": "c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7"
      },
      "serviceAdvisor": {
        "uuid": "b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6",
        "firstName": "Service",
        "lastName": "Advisor",
        "roleName": "Service Advisor",
        "departmentUuid": "a64b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
        "userUuid": "c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7"
      },
      "primaryDriver": {
        "uuid": "d97e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2",
        "firstName": "John",
        "lastName": "Smith",
        "roleName": "Driver",
        "departmentUuid": "a64b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
        "userUuid": "e08f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3"
      },
      "secondaryDriver": null,
      "isValid": true,
      "createdDate": "2025-10-30T10:24:05-0700",
      "driverPayments": [
        {
          "driverUuid": "d97e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2",
          "dollarPerMinute": 0.0,
          "amountForMinutes": 0.0,
          "dollarPerMile": 0.0,
          "amountForMiles": 0.0,
          "dollarPerTrip": 0.0,
          "amountForTrip": 0.0,
          "totalAmount": 0.0,
          "salariedTotal": null,
          "tripDetails": {
            "startTime": "2025-10-30T17:27:01+0000",
            "startDrivingTime": "2025-10-30T17:27:07+0000",
            "outboundCompleteTime": "2025-10-30T17:27:20+0000",
            "inboundStartTime": "2025-10-30T17:28:26+0000",
            "endDrivingTime": "2025-10-30T17:28:31+0000",
            "endTime": "2025-10-30T17:29:37+0000",
            "totalTimeInMinutes": 2,
            "distanceTravelledInMiles": 2458.63,
            "maxSpeed": 0.0
          }
        }
      ],
      "docStatus": null,
      "customerProfileToken": null,
      "linkedAppointmentUuid": null,
      "linkedTripUuids": []
    }
  ]
}

Request​

HTTP request​

Parameters​

Request body:​

Authorization​

Endpoint​

Response​

Example​

Example Request​

Example Response​