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"
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": [
        {
          "fieldName": "string",
          "fieldValue": "string"
        }
      ],
      "createdOn": "timestamp",
      "updatedOn": "timestamp"
    }
  ]
}

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	Name of the declined service
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 for the service
source	String	Source of the decline (e.g., "Service Cart", "Scheduler")
status	String	Current status (e.g., "Declined", "Approved", "Marked Green", "Deleted")
isObselete	Boolean	Whether the PDR is obsolete
isCustom	Boolean	Whether it's a custom recommendation
fieldList	List\<FieldDTO>	Additional custom fields
createdOn	Date	Timestamp when PDR was created
updatedOn	Date	Timestamp when PDR was last updated

Error Response

HTTP Status: 500 Internal Server Error (or appropriate error code)

{
  "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"
    }
  }'

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

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