How to get factory-menus

This document is designed to help you understand how you can fetch a list of all the factory-menus owned by a dealership and use filters. To get this data, 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.

The endpoint mentioned below can be used to get the list of all the factory-menus owned by a dealership.

Currently, the required attributes to fetch factory menus are mileageDTOList, brandUuidList, and any one of the following vehicle information.

Vehicle Information
VIN
make, model & year
myKaarma vehicle UUID
baseVehicleId

If you don't have brandUuidList, ask your mykaarma API representative.

Note that you need to show the models and years from mykaarma in your schedule to use the model and year parameter to fetch factory menus. Otherwise, there may be an issue with matching the names of the models with mykaarma. If you don't use mykaarma models and do not have other parameters to fetch menus, talk to your mykaarma API representative to discuss further.

To pass the Factory Menu in the Create Appointment API, include the following three attributes in the serviceList parameter:

Parameter in `serviceList` (Create Appointment API)	Description	Corresponding Parameter in Factory Menu Response
`menuUuid`	Identifies the menu	`uuid`
`operationType`	Type of the menu. Example: `SERVICEMOTORSMAINTENANCEMENU`	`operationType`
`title` or `operationUuid`	Identifies the opcode attached to the menu	For `title` - `laborOpCode`, For `operationUuid` - `quickOpLiteUuid`

Sample `serviceList` Object to Pass in Create Appointment API

"serviceList": [
  {
    "title": "{laborOpCode}",
    "operationUuid": "{quickOpLiteUuid}",
    "menuUuid": "{uuid}",
    "operationType": "{operationType}"
  }
]

To process your request, we will utilize the provided vehicle and mileage information to identify the corresponding factory menu.

Process:

Exact Match Search: We will first attempt to locate a factory menu that precisely matches the provided vehicle and mileage specifications.
Nearest Mileage Approximation: If an exact match is not found, we will search for the closest available factory menu based on mileage.
Response Structure: The response will include the selected factory menu and a "mileage" field. This field will indicate the mileage for which the returned menu is applicable.

Mileage Approximation Logic:

For instance, if the input mileage is 12,000 miles and factory menus exist for 10,000 and 20,000 miles, the 10,000-mile menu will be returned.
Specifically, the 10,000 mile menu will be returned for input mileages ranging from 10,000 to 14,999 miles. The 20,000 mile menu will be returned for input mileages ranging from 15,000 to 20,000 miles.

This methodology ensures that you receive the most relevant and applicable factory menu based on your vehicle and mileage information.

Request

HTTP request

POST https://api.mykaarma.com/opcodes/v1/dealers/{{dealerUUID}}/factory-menus/searches

Parameters

Parameter Name	Value	Description
`dealerUUID`	`string`	Unique identifier (UUID) of the dealership for which you want to fetch the operation codes

Authorization

This request requires following scopes

Scope	Level	Description
`kopcode.factory.menu.read`	`Dealer`	Authorizes client to get factory-menus for given dealership

Request Body

Required Parameters

The API requires the following parameters:

mileageDTOList
typeList

Additional Required Parameters

In addition to the above, you must include at least one of the following combinations of parameters:

vin
make,model,year
brandUuidList,vehicleUuid
brandUuidList,baseVehicleId

Note: To use Make, Model, and Year, you must first obtain the corresponding information from myKaarma to avoid any mismatches in naming.

All Supported Parameters

Parameter Name	Value	Required	Description
`startPosition`	`number`	No	The starting position for paginated results. This field is used to define the beginning index for fetching records.
`endPosition`	`number`	No	The ending position for paginated results. This field is used to define the last index for fetching records.
`isLastPage`	`boolean`	No	A flag indicating if the current set of results is the last page. If `true`, no further pages are available.
`resultSize`	`number`	No	The number of results returned in the current response. This field indicates the size of the result set.
`uuidList`	`list<string>`	No	A list of unique identifiers (UUIDs) of the operation codes. Each string in the array corresponds to a specific factory menus.
`mileageDTOList`	`list<MileageDTO>`	Yes	This is a list of Mileage Data Transfer Objects (DTOs) that includes the `startMileage`. Please provide the vehicle mileage in the `startMileage` field, and ensure that only one mileage entry is included in the list. While this is a list, note that the current API does not support fetching Factory Menus for multiple mileages in a single request. For further clarification, please refer to the sample cURL request. Example - if you want to fetch Factory Menu's for a vehicle with 12,000 Miles, then just pass 12000 in the `startMileage` field.
`baseVehicleId`	`number`	No	The identifier for the base vehicle. This ID is used to specify the base model or type of vehicle associated with the operation codes.
`engineId`	`number`	No	The identifier for the engine. This field is used to specify the engine type associated with the operation codes.
`severityFlag`	`string`	No	A flag or indicator of the severity level associated with the operation codes. The value could represent different levels of severity (`NORMAL`, `SEVERE`).
`brandUuidList`	`list<string>`	No	A list of brand uuids associated with the operation codes. Each string in the array represents a specific brand.
`vin`	`string`	No	VIN of the vehicle.
`model`	`string`	No	model of the vehicle.
`year`	`string`	No	year of the vehicle.
`vehicleUuid`	`string`	No	A Unique identifier of the vehicle at myKaarma.
`make`	`string`	No	Make or Brand name of the vehicle at myKaarma.
`typeList`	`list<string>`	Yes	A list of types related to the request. Each string in the array represents a specific type, such as `SERVICEMOTORSMAINTENANCEMENU`, and `SERVICEMOTORSLINEITEM`. At present, we recommend just using `SERVICEMOTORSMAINTENANCEMENU` in this list in your request.

Curl

curl -X POST "https://api.mykaarma.com/opcodes/v1/dealers/{{dealerUuid}}/factory-menus/searches"
--header 'accept: application/json' \
-u "{{username}}:{{password}}" \
--header 'Content-Type: application/json' \
--data-raw '{
  "startPosition": {{startPosition}},
  "endPosition": {{endPosition}},
  "isLastPage": {{isLastPage}},
  "resultSize": {{resultSize}},
  "uuidList": {{uuidList}},
  "typeList": {{typeList}},
  "mileageDTOList": [
    {
      "startMileage": {{startMileage}}
    }
  ],
  "baseVehicleId": {{baseVehicleId}},
  "engineId": {{engineId}},
  "make": {{make}},
  "vehicleUuid": {{vehicleUuid}},
  "year": {{year}},
  "model": {{model}},
  "vin": {{vin}},
  "brandUuidList": {{brandUuidList}},
}'

Response

{
  "errors": [
    {
      "errorName": "string",
      "errorMessage": "string",
      "errorCode": 0
    }
  ],
  "warnings": [
    {
      "warningCode": "string",
      "warningTitle": "string",
      "warningMessage": "string"
    }
  ],
  "statusCode": 0,
  "apiRequestId": "string",
  "operationDTOList": [
    {
      "laborOpCode": "string",
      "opCodeName": "string",
      "description": "string",
      "totalPrice": "string",
      "opCodeDurationInMinutes": "string",
      "isValid": true,
      "uuid": "string",
      "inMobileService": true,
      "inOnlineScheduler": true,
      "communicationCode": "string",
      "payType": "string",
      "inServiceCart": true,
      "inDealerAppScheduler": true,
      "dmsDescription": "string",
      "laborPrice": "string",
      "dmsLaborPrice": "string",
      "partsPrice": "string",
      "dmsPartsPrice": "string",
      "taxAmount": "string",
      "dmsTaxAmount": "string",
      "dmsTotalPrice": "string",
      "sortOrder": 0,
      "correction": "string",
      "cause": "string",
      "soldHours": 0,
      "dispatchCode": "string",
      "comebackFlag": true,
      "usagePercentile": 0,
      "position": 0,
      "leadTimeInMinutes": 0,
      "isIndexed": true,
      "isDefault": true,
      "notes": "string",
      "serviceType": "string",
      "serviceTypeServiceCart": "string",
      "recallId": "string",
      "vehicleMileageConfigDTOList": [
        {
          "brandDTO": {
            "id": 0,
            "name": "string",
            "motorsMakeId": 0,
            "motorsMakeName": "string"
          },
          "year": "string",
          "model": "string",
          "trim": "string",
          "engine": "string",
          "mileageUuid": "string",
          "uuid": "string",
          "motorsBaseVehicleId": "string",
          "motorsEngineId": "string",
          "isValid": true
        }
      ],
      "dailyLimitConfigDTOList": [
        {
          "dayNumber": 0,
          "dayLimit": 0
        }
      ],
      "pullEstimateInSC": true,
      "miscPrice": "string",
      "useDmsPrice": true,
      "showDmsPriceMismatchWarning": true,
      "noPartsNeeded": true,
      "inCheckIn": true,
      "quickOpLiteUuid": "string",
      "invoiceLineList": [
        "string"
      ],
      "menuName": "string",
      "operationType": "OPCODE",
      "dealerUuid": "string",
      "isCustomConcern": true,
      "taxonomyId": 0,
      "severityFlag": "string",
      "isSeverityNormal": true,
      "isSeveritySevere": true,
      "notesSevere": [
        "string"
      ],
      "notesNormal": [
        "string"
      ],
      "motorsOperationName": "string",
      "mileage": 0,
      "motorsMake": "string",
      "motorsMakeId": 0,
      "totalPriceForConversion": 0
    }
  ],
  "totalCount": 0,
  "mkAndDmsSimilarOpcodeCount": 0,
  "pricingVisibleToCustomer": true
}

Sample Response

{
    "errors": null,
    "warnings": null,
    "statusCode": 200,
    "apiRequestId": "c043b46a-7f03-4bc8-a7d9-22620bc97bbe",
    "operationDTOList": [
        {
            "laborOpCode": "30K",
            "opCodeName": "30K/3 YR SCHEDULED MAINTENANCE",
            "description": "OIL AND FILTER CHANGE AND MULTI-POINT VISUAL INSPECTION.  IF DIESEL, ALSO DRAIN WATER FROM FUEL FILTER, AND FILL ADBLUE.",
            "totalPrice": null,
            "opCodeDurationInMinutes": null,
            "isValid": true,
            "uuid": "b1u6v1ceadIzjrIYiPVqaK2V_axRMPw22vM9UQLDBq0",
            "inMobileService": false,
            "inOnlineScheduler": false,
            "communicationCodes": null,
            "payType": null,
            "inServiceCart": false,
            "inDealerAppScheduler": true,
            "dmsDescription": "CUSTOMER REQUESTS THE 30K OIL AND FILTER CHANGE AND MULTI-POINT VISUAL INSPECTION.  IF DIESEL, ALSO DRAIN WATER FROM FUEL FILTER, AND FILL ADBLUE.",
            "laborPrice": null,
            "dmsLaborPrice": null,
            "partsPrice": null,
            "dmsPartsPrice": null,
            "taxAmount": null,
            "dmsTaxAmount": null,
            "dmsTotalPrice": null,
            "sortOrder": null,
            "correction": null,
            "cause": null,
            "soldHours": null,
            "dispatchCode": null,
            "comebackFlag": null,
            "usagePercentile": null,
            "position": 0,
            "leadTimeInMinutes": null,
            "isIndexed": true,
            "isDefault": null,
            "notes": null,
            "serviceType": null,
            "serviceTypeServiceCart": null,
            "recallId": null,
            "vehicleMileageConfigDTOList": [
                {
                    "brandDTO": {
                        "id": null,
                        "name": null,
                        "motorsMakeId": 2,
                        "motorsMakeName": "Porsche"
                    },
                    "year": null,
                    "model": null,
                    "trim": null,
                    "engine": null,
                    "mileageUuid": "DZ8GPo4RnBphcpb6SbsjGORL-sJwAmHSnDsQLOvxIoo",
                    "uuid": null,
                    "motorsBaseVehicleId": "84",
                    "motorsEngineId": "185",
                    "isValid": null
                }
            ],
            "dailyLimitConfigDTOList": null,
            "pullEstimateInSC": null,
            "miscPrice": null,
            "useDmsPrice": null,
            "showDmsPriceMismatchWarning": null,
            "noPartsNeeded": null,
            "inCheckIn": null,
            "quickOpLiteUuid": "WjSR3tYxEOsX5De_XZJe43ZBo3KTyxZY3VU7Zyi0ekE",
            "invoiceLineList": [
                {
                    "laborOpCode": null,
                    "opCodeName": null,
                    "description": null,
                    "totalPrice": null,
                    "opCodeDurationInMinutes": null,
                    "isValid": true,
                    "uuid": "XlcXeAZ9mDC2HLYewQB-n5s6JygGlcOMcyouw2gLnYk",
                    "inMobileService": null,
                    "inOnlineScheduler": null,
                    "communicationCodes": null,
                    "payType": null,
                    "inServiceCart": null,
                    "inDealerAppScheduler": null,
                    "dmsDescription": null,
                    "laborPrice": null,
                    "dmsLaborPrice": null,
                    "partsPrice": null,
                    "dmsPartsPrice": null,
                    "taxAmount": null,
                    "dmsTaxAmount": null,
                    "dmsTotalPrice": null,
                    "sortOrder": null,
                    "correction": null,
                    "cause": null,
                    "soldHours": null,
                    "dispatchCode": null,
                    "comebackFlag": null,
                    "usagePercentile": null,
                    "position": 0,
                    "leadTimeInMinutes": null,
                    "isIndexed": true,
                    "isDefault": null,
                    "notes": null,
                    "serviceType": "Service",
                    "serviceTypeServiceCart": null,
                    "recallId": null,
                    "vehicleMileageConfigDTOList": null,
                    "dailyLimitConfigDTOList": null,
                    "pullEstimateInSC": null,
                    "miscPrice": null,
                    "useDmsPrice": null,
                    "showDmsPriceMismatchWarning": null,
                    "noPartsNeeded": null,
                    "inCheckIn": null,
                    "quickOpLiteUuid": null,
                    "invoiceLineList": null,
                    "menuName": null,
                    "operationType": "SERVICEMOTORSLINEITEM",
                    "dealerUuid": "111b2de0b812fc8c1e408dede951d60d8c62d54da0c0269c43aa6a15ae7aff18",
                    "isCustomConcern": null,
                    "taxonomyId": 11747,
                    "severityFlag": null,
                    "isSeverityNormal": true,
                    "isSeveritySevere": null,
                    "notesSevere": null,
                    "notesNormal": null,
                    "motorsOperationName": "Engine Oil Filter R&R",
                    "mileage": 40000,
                    "motorsMake": "Porsche",
                    "motorsMakeId": 2,
                    "totalPriceForConversion": 0.0
                }
            ],
            "menuName": "30000 miles maintenance schedule",
            "operationType": "SERVICEMOTORSMAINTENANCEMENU",
            "dealerUuid": "c01e46c0bfdc4ef5110a36ddf5826f8d0b8e7a4897e99f89d88248dcc7bff48b",
            "isCustomConcern": null,
            "taxonomyId": 0,
            "severityFlag": null,
            "isSeverityNormal": null,
            "isSeveritySevere": null,
            "notesSevere": null,
            "notesNormal": null,
            "motorsOperationName": "30000 miles maintenance schedule",
            "mileage": null,
            "motorsMake": "Porsche",
            "motorsMakeId": 2,
            "totalPriceForConversion": 0.0
        }
    ],
    "totalCount": 196,
    "mkAndDmsSimilarOpcodeCount": null,
    "pricingVisibleToCustomer": null
}

Operation data model

Please refer to operation data model to see all the parameters you will get when you get opcodes and factory menus from myKaarma APIs or events.

How to get factory-menus

How to Pass Factory Menu in Create Appointment API

Sample `serviceList` Object to Pass in Create Appointment API

Factory Menu Retrieval Process

Process:

Mileage Approximation Logic:

Request

HTTP request

Parameters

Authorization

Request Body

Required Parameters

Additional Required Parameters

All Supported Parameters

Curl

Response

Sample Response

Operation data model

How to Pass Factory Menu in Create Appointment API​

Sample serviceList Object to Pass in Create Appointment API​

Factory Menu Retrieval Process​

Process:​

Mileage Approximation Logic:​

Request​

HTTP request​

Parameters​

Authorization​

Request Body​

Required Parameters​

Additional Required Parameters​

All Supported Parameters​

Curl​

Response​

Sample Response​

Operation data model​

How to Pass Factory Menu in Create Appointment API

Sample `serviceList` Object to Pass in Create Appointment API

Factory Menu Retrieval Process

Process:

Mileage Approximation Logic:

Request

HTTP request

Parameters

Authorization

Request Body

Required Parameters

Additional Required Parameters

All Supported Parameters

Curl

Response

Sample Response

Operation data model