How to fetch declined services

Overview

Fetches previously declined service recommendations based on specified filters. This endpoint retrieves historical data about service recommendations that were declined by customers.

Endpoint Details

• URL: https://api.mykaarma.com/declinedservices/v1/dealer/{dealerUuid}/pdr/fetch
• Method: POST
• Authentication: Required (Bearer Token)

Authorization

This request requires the following authorization scopes:

Scope	Level	Description
declinedservices.fetch	Dealer	Authorizes client to fetch previously declined services

Request

Path Parameters

Parameter	Type	Required	Description
dealerUuid	String	✅ Yes	Unique identifier for the dealer

Headers

Header	Type	Required	Description
authorization	String	✅ Yes	Bearer token for authentication
Content-Type	String	✅ Yes	application/json

Request Body

Type: FetchPdrRequest

{
  "pdrFilters": {
    "customerUUIDList": ["string"],
    "vehicleUUIDList": ["string"],
    "startDate": "string (ISO 8601 format)",
    "endDate": "string (ISO 8601 format)",
    "lastPageToken": "string",
    "pageSize": "integer",
    "pdrStatusList": ["string"],
    "pdrUUIDList": ["string"],
    "declineSourceList": ["string"]
  }
}

Request Body Parameters

pdrFilters Object

Field	Type	Required	Description
customerUUIDList	List\<String>	✅ Yes	Mandatory - List of customer UUIDs to filter PDRs
vehicleUUIDList	List\<String>	No	Optional - List of vehicle UUIDs to filter PDRs
startDate	String	No	Filter PDRs created on or after this date (ISO 8601 format)
endDate	String	No	Filter PDRs created on or before this date (ISO 8601 format)
lastPageToken	String	No	Token for pagination - use to fetch next page of results
pageSize	Integer	No	Number of records per page
pdrStatusList	List\<String>	No	Filter by PDR status. Valid values: "Declined", "Approved", "Marked Green", "Deleted", "Undecided"
pdrUUIDList	List\<String>	No	Filter by specific PDR UUIDs
declineSourceList	List\<String>	No	Filter by decline source. Valid values: "Service Cart", "Scheduler"

Response

Success Response

HTTP Status: 200 OK

Response Type: FetchPdrResponse

{
  "statusCode": 200,
  "errors": [],
  "warnings": [],
  "pdrList": [
    {
      "uuid": "string",
      "dealerUUID": "string",
      "customerUUID": "string",
      "vehicleUUID": "string",
      "declinedName": "string",
      "declinedDescription": "string",
      "orderUUID": "string",
      "orderNumber": "string",
      "mpiUUID": "string",
      "inspectionTypeUUID": "string",
      "recommendationUUID": "string",
      "technicianUUID": "string",
      "technicianName": "string",
      "serviceAdvisorUUID": "string",
      "serviceAdvisorName": "string",
      "removalReason": "string",
      "removalComment": "string",
      "opCode": "string",
      "source": "string",
      "status": "string",
      "isObselete": boolean,
      "isCustom": boolean,
      "fieldList": [
        {
          "type": "string",
          "description": "string",
          "value": "string",
          "state": "string",
          "unit": "string",
          "sortOrder": "string"
        }
      ],
      "createdOn": "string",
      "updatedOn": "string",
      "timesRecommended": integer
    }
  ]
}

Response Fields

Field	Type	Description
statusCode	Integer	HTTP status code
errors	List\<ApiError>	List of errors if any occurred
warnings	List\<ApiWarning>	List of warnings if any
pdrList	List\<PreviousDeclinedRecommendation>	List of declined service recommendations matching the filters

PreviousDeclinedRecommendation Object Fields

Field	Type	Description
uuid	String	Unique identifier for the PDR
dealerUUID	String	Dealer's unique identifier
customerUUID	String	Customer's unique identifier
vehicleUUID	String	Vehicle's unique identifier
declinedName	String	Human-readable name of the declined service recommendation (e.g., "Check Battery for Condition"). This is the recommendation label from the MPI inspection — it is not the opcode. See opCode for the opcode value.
declinedDescription	String	Description of the declined service
orderUUID	String	Associated order UUID
orderNumber	String	Associated order number
mpiUUID	String	Multi-point inspection UUID
inspectionTypeUUID	String	Inspection type UUID
recommendationUUID	String	Original recommendation UUID
technicianUUID	String	Technician's UUID who created the recommendation
technicianName	String	Technician's name
serviceAdvisorUUID	String	Service advisor's UUID
serviceAdvisorName	String	Service advisor's name
removalReason	String	Reason for declining the service
removalComment	String	Additional comments about the decline
opCode	String	Operation code (opcode) for the service. Only populated for records with status Declined or Undecided. Empty string for other statuses.
source	String	Source of the decline (e.g., "Service Cart", "Scheduler")
status	String	Current status (e.g., "Declined", "Approved", "Marked Green", "Deleted", "Undecided")
isObselete	Boolean	true when this record is no longer actionable. Always false in fetch results — the endpoint filters these out automatically. See isObselete Lifecycle below. Note: field name contains a known typo ("Obselete").
isCustom	Boolean	true if this recommendation was manually added by the service advisor (not generated from the MPI inspection template).
fieldList	List\<FieldDTO>	MPI inspection button states recorded at time of recommendation. Each item captures the button type, technician-selected value, and color state. See FieldDTO Object Fields below.
createdOn	String	UTC timestamp when PDR was created. ISO 8601 format with millisecond precision (e.g., "2026-03-11T10:34:47.505+0000").
updatedOn	String	UTC timestamp when PDR was last updated. ISO 8601 format with millisecond precision (e.g., "2026-04-01T08:18:46.307+0000").
timesRecommended	Integer	Number of times this service has been recommended to the customer

isObselete Lifecycle

Records returned by this endpoint always have isObselete: false — the fetch query filters obsolete records automatically and there is no way to retrieve them through this endpoint.

A record is marked isObselete: true (and removed from future fetch results) by two triggers:

1. Service approved or performed

When the same service is approved or performed on the same customer+vehicle during a visit, the system marks the previously declined PDR as obsolete. The match uses the best available identifier, in order:

• Direct PDR UUID (most precise)
• Opcode match (for opcode-based recommendations)
• Name+field count match (fallback)

2. Time-based retiring

After each service order is processed, the system scans all active Declined/Undecided PDRs for the customer+vehicle. Any PDR that was not re-presented in the current visit and whose updatedOn timestamp is older than the dealer's retiring window is automatically marked obsolete. The default retiring window is 90 days and is configurable per dealer.

Re-declines and timesRecommended

When the same service is declined again on a new visit, isObselete is generally not set — instead timesRecommended is incremented on the existing record. For standard (non-opcode) recommendations with a known PDR UUID, the same record is updated in-place with the new visit's data. timesRecommended therefore reflects how many visits this service has been recommended across, not the number of times on a single visit.

FieldDTO Object Fields

Each item in fieldList represents an MPI inspection button associated with the recommendation at the time it was declined. It captures the condition state the technician recorded.

Field	Type	Description
type	String	Inspection button type identifier (e.g., "button-rrg" for Red/Replace/Green, "button-fcp" for Fail/Caution/Pass)
description	String	Optional label for the field. May be empty.
value	String	The value selected by the technician (e.g., "Replace", "Fail")
state	String	Color state at time of inspection (e.g., "red", "yellow", "green")
unit	String	Unit of measurement if applicable (e.g., "miles", "psi"). May be absent.
sortOrder	String	Display order of this field among multiple fields

Example fieldList entry (from dev):

{
  "type": "button-rrg",
  "description": "",
  "value": "Replace",
  "state": "red",
  "sortOrder": "1"
}

Error Responses

401 Unauthorized

Returned when the authorization header is missing or the token is invalid.

{
  "statusCode": 401,
  "errors": [
    {
      "errorCode": "string",
      "errorMessage": "Unauthorized"
    }
  ],
  "warnings": []
}

403 Forbidden

Returned when the token is valid but lacks the required declinedservices.fetch scope or is not authorized for the specified dealer.

{
  "statusCode": 403,
  "errors": [
    {
      "errorCode": "string",
      "errorMessage": "Forbidden"
    }
  ],
  "warnings": []
}

500 Internal Server Error

Returned when an unexpected server-side error occurs.

{
  "statusCode": 500,
  "errors": [
    {
      "errorCode": "FETCH_PDR_ERROR",
      "errorMessage": "Error description"
    }
  ],
  "warnings": []
}

Examples

Example 1: Basic Fetch PDRs (Mandatory Fields Only)

Request:

curl -X POST \
  https://api.mykaarma.com/declinedservices/v1/dealer/abc123-def456-ghi789/pdr/fetch \
  -H 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "pdrFilters": {
      "customerUUIDList": ["customer-uuid-123"]
    }
  }'

Example 2: Fetch PDRs with Date Range

Request:

curl -X POST \
  https://api.mykaarma.com/declinedservices/v1/dealer/abc123-def456-ghi789/pdr/fetch \
  -H 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "pdrFilters": {
      "customerUUIDList": ["customer-uuid-1", "customer-uuid-2"],
      "vehicleUUIDList": ["vehicle-uuid-1", "vehicle-uuid-2"],
      "startDate": "2026-01-01T00:00:00Z",
      "endDate": "2026-01-11T23:59:59Z",
      "pageSize": 50
    }
  }'

Example 3: Fetch PDRs with Status Filter

Request:

curl -X POST \
  https://api.mykaarma.com/declinedservices/v1/dealer/abc123-def456-ghi789/pdr/fetch \
  -H 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "pdrFilters": {
      "customerUUIDList": ["customer-uuid-123"],
      "vehicleUUIDList": ["vehicle-uuid-456"],
      "pdrStatusList": ["Declined", "Approved"]
    }
  }'

Example 4: Fetch PDRs with Pagination

Request:

curl -X POST \
  https://api.mykaarma.com/declinedservices/v1/dealer/abc123-def456-ghi789/pdr/fetch \
  -H 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "pdrFilters": {
      "customerUUIDList": ["customer-uuid-123"],
      "vehicleUUIDList": ["vehicle-uuid-456"],
      "pageSize": 20,
      "lastPageToken": "previous_page_token_here"
    }
  }'

Example 5: Fetch PDRs by Source

Request:

curl -X POST \
  https://api.mykaarma.com/declinedservices/v1/dealer/abc123-def456-ghi789/pdr/fetch \
  -H 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "pdrFilters": {
      "customerUUIDList": ["customer-uuid-123"],
      "vehicleUUIDList": ["vehicle-uuid-456"],
      "declineSourceList": ["Service Cart"],
      "pdrStatusList": ["Declined"]
    }
  }'

Example 6: Fetch Multiple Customers and Vehicles

Request:

curl -X POST \
  https://api.mykaarma.com/declinedservices/v1/dealer/abc123-def456-ghi789/pdr/fetch \
  -H 'authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "pdrFilters": {
      "customerUUIDList": [
        "customer-uuid-1",
        "customer-uuid-2",
        "customer-uuid-3"
      ],
      "vehicleUUIDList": [
        "vehicle-uuid-1",
        "vehicle-uuid-2",
        "vehicle-uuid-3"
      ],
      "startDate": "2025-12-01T00:00:00Z",
      "endDate": "2026-01-11T23:59:59Z"
    }
  }'

Sample Response Objects

The following are real response objects from the development environment, illustrating two common scenarios.

Sample 1: Declined PDR with "Fail" recommendation

{
  "uuid": "69d381564ec0fd0ce3ec1b91",
  "dealerUUID": "cb731d36fd635ddd6ef8dd43500892b0c0249d1c01a46dbcc445a809c0a8e3b2",
  "customerUUID": "SxDKog9EEhwNi0ejz9N4nwPA9uZ9EKoiPI7J4DQSF4U",
  "vehicleUUID": "Lv0Gpb4pDRnxkHFlkonpZtFk63l5aELA01C-DJDWTBs",
  "declinedName": "Fluid Leaks (coolant, engine oil, misc.) ",
  "declinedDescription": "",
  "orderUUID": "68oUtnAYX73G1V_B5lSkGGuZGGa45mkAkwH3cHjRmEE",
  "orderNumber": "myk3191960",
  "mpiUUID": "VX6hli3DKwGwNqXKnEL4BCY9T6HZFmqF7WYnejsuTkc",
  "inspectionTypeUUID": "gmCYgFB7qarrcGLjbkIbtQWkdJWdtLSU3VeCX3GMVmk",
  "recommendationUUID": "b5DpmntXk5Vh7j0CKb4L1BKC-HL3IfHXv4iFVbTaKvE",
  "technicianUUID": "678074265e2e983b392921c34f8ff76e91d7571d473da82460275c0b89882aa4",
  "technicianName": "John Tech",
  "serviceAdvisorUUID": "80c9166f65eecad91e3855555198156470d9cd3e5d7a95841c3a2a7086d1c87a",
  "serviceAdvisorName": "Jane Advisor",
  "removalReason": "",
  "removalComment": "",
  "opCode": "",
  "source": "Service Cart",
  "status": "Declined",
  "isObselete": false,
  "isCustom": false,
  "fieldList": [
    {
      "type": "button-fcp",
      "description": "",
      "value": "Fail",
      "state": "red",
      "sortOrder": "1"
    }
  ],
  "timesRecommended": 2,
  "createdOn": "2026-04-06T09:48:06.298+0000",
  "updatedOn": "2026-04-06T09:53:29.485+0000"
}

Notes on this object:

• status: "Declined" — customer explicitly declined the service recommendation
• fieldList[0].type: "button-fcp" — Fail/Caution/Pass inspection button; technician selected "Fail" in "red" state
• timesRecommended: 2 — this service was recommended twice across previous visits
• No removalReason or removalComment — these are empty for actively declined PDRs (no manual removal)

Sample 2: Undecided PDR with "Fail" recommendation

{
  "uuid": "69b3e075c97d600d5a278a4a",
  "dealerUUID": "cb731d36fd635ddd6ef8dd43500892b0c0249d1c01a46dbcc445a809c0a8e3b2",
  "customerUUID": "SxDKog9EEhwNi0ejz9N4nwPA9uZ9EKoiPI7J4DQSF4U",
  "vehicleUUID": "Lv0Gpb4pDRnxkHFlkonpZtFk63l5aELA01C-DJDWTBs",
  "declinedName": "Windshield Washer Fluid",
  "declinedDescription": "",
  "orderUUID": "S5teLFgGEnCdIYsvCF2jYef5ANMWRgpNclcoJwn3aBk",
  "orderNumber": "myk6204300",
  "mpiUUID": "uY0rTD22Eyr5G4wRlbjl-rfJA-1t9NJl25aZRyozlPA",
  "inspectionTypeUUID": "gmCYgFB7qarrcGLjbkIbtQWkdJWdtLSU3VeCX3GMVmk",
  "recommendationUUID": "G7W7G69PsD-qwK7-rFIqtYphdidBGhf2Xo7i2Cc_04Y",
  "technicianUUID": "678074265e2e983b392921c34f8ff76e91d7571d473da82460275c0b89882aa4",
  "technicianName": "John Tech",
  "serviceAdvisorUUID": "80c9166f65eecad91e3855555198156470d9cd3e5d7a95841c3a2a7086d1c87a",
  "serviceAdvisorName": "Jane Advisor",
  "removalReason": "",
  "removalComment": "",
  "opCode": "",
  "source": "Service Cart",
  "status": "Undecided",
  "isObselete": false,
  "isCustom": false,
  "fieldList": [
    {
      "type": "button-fcp",
      "description": "",
      "value": "Fail",
      "state": "red",
      "sortOrder": "1"
    }
  ],
  "timesRecommended": 3,
  "createdOn": "2026-03-13T10:01:25.729+0000",
  "updatedOn": "2026-03-27T12:13:15.479+0000"
}

Notes on this object:

• status: "Undecided" — customer neither approved nor explicitly declined at visit end
• fieldList[0].type: "button-fcp" — Fail/Caution/Pass inspection button; technician selected "Fail" in "red" state
• timesRecommended: 3 — recommended 3 times across prior visits
• No removalReason or removalComment because the service was not explicitly declined

Note: Technician and advisor names in sample objects above are anonymized from the actual dev data.

Enumerations

PDR Status Values

• "Declined" - Service recommendation was declined
• "Approved" - Service recommendation was approved
• "Marked Green" - Service marked as green status
• "Deleted" - PDR has been deleted
• "Undecided" - Service recommendation status is undecided

Decline Source Values

• "Service Cart" - Declined from service cart
• "Scheduler" - Declined from scheduler

Authorization

This endpoint requires:

• Valid authentication token in the authorization header
• The token must have declinedservices.fetch dealer level scope
• The authenticated user must be authorized for the specified dealer

Authorization Check:

• The system validates that the authenticated user has permission to access data for the provided dealerUuid
• If authorization fails, an appropriate error response is returned

Important Notes

⚠️ customerUUIDList is a MANDATORY field - requests without this will fail

• You can provide multiple customer UUIDs in the list
• vehicleUUIDList is optional and can be used to further filter results by specific vehicles
• All other filters in pdrFilters are optional and can be combined
• Date fields should be in ISO 8601 format
• Use lastPageToken for pagination when fetching large datasets
• The pageSize parameter controls how many records are returned per request
• The endpoint returns PDRs that match the specified customer UUIDs along with any additional filters applied

Validation Rules

• customerUUIDList must not be null or empty
• vehicleUUIDList is optional - if provided, must be a valid list
• If provided, date ranges must have valid ISO 8601 format
• Status values must match the predefined enum values
• Source values must match the predefined enum values