How to Get Video Grader Data

This document explains how to fetch the video grader results for the inspections on an order. The video grader scores each technician video on the inspection (introduction, vehicle checks, value building and overall delivery). To use this endpoint, you first need your credentials. If you don't already have them, head over to the Authentication and Authorization page to see how to request credentials from us.

Request

HTTP Request

GET https://api.mykaarma.com/scprocessor/mpi/aggregator/v1/dealer-departments/{dealer-department-uuid}/orders/{order-uuid}/video-grader

Parameters

Required path parameters:

Parameter Name	Value	Description
`dealer-department-uuid`	`string`	UUID of the dealer department the order belongs to
`order-uuid`	`string`	UUID of the order whose inspections you want video grader data for

Authorization

This request requires the following authorization scope:

Scope	Level	Description
`inspection.video.grader.read`	`DealerDepartment`	Authorizes the client to read video grader data for inspections in the department

Example

curl -X GET "https://api.mykaarma.com/scprocessor/mpi/aggregator/v1/dealer-departments/dept-uuid-123/orders/order-uuid-456/video-grader" \
-H "accept: application/json" \
-u "{{username}}:{{password}}"

Response

Success Response (200 OK)

{
  "statusCode": 200,
  "errors": null,
  "warnings": null,
  "inspectionToVideoGraderDetailsDTOMap": {
    "mpi-uuid-789": {
      "videoAnalysisList": [
        {
          "uuid": "analysis-uuid-1",
          "videoGraderUuid": "video-grader-uuid-1",
          "attachmentUrl": "https://example.com/video.mp4",
          "mpiUuid": "mpi-uuid-789",
          "dealerDepartmentUUID": "dept-uuid-123",
          "technicianIdentifiers": {
            "dealerAssociateUUID": "da-uuid-1",
            "dealerAssociateName": "Technician Name"
          },
          "serviceAdvisorIdentifiers": {
            "dealerAssociateUUID": "da-uuid-2",
            "dealerAssociateName": "Advisor Name"
          },
          "assessmentsByCategory": {
            "Vehicle Checks": [
              {
                "assessment": {
                  "assessmentId": 9,
                  "name": "WIPER",
                  "label": "Wiper",
                  "assessmentType": "visual",
                  "category": "Vehicle Checks",
                  "isAssessmentVisible": true
                },
                "detections": [
                  {
                    "timestamp": 12.5,
                    "frameNumber": 375,
                    "label": "Wiper",
                    "confidence": 0.91,
                    "bbox": [0.12, 0.34, 0.56, 0.78]
                  }
                ],
                "status": "Showed",
                "videoGraderLiteFeedbackDTOList": [],
                "score": 1.0,
                "isCheckDisabled": false
              }
            ]
          },
          "dealerIdentifiers": {
            "dealerUUID": "dealer-uuid-1",
            "dealerName": "Dealer Name"
          },
          "orderIdentifiers": {
            "orderUUID": "order-uuid-456",
            "orderNumber": "123456"
          },
          "inspectionTypeIdentifiersDTO": {
            "inspectionTypeUuid": "inspection-type-uuid-1",
            "inspectionTypeName": "Multi Point Inspection"
          },
          "videoSentStatus": "SENT",
          "videoViewedStatus": true,
          "mileage": 25000,
          "createdOn": 1760000000000,
          "duration": 120,
          "gradingDurationMillis": 45000,
          "hasProfanity": false,
          "audioQuality": 4,
          "wordCount": 310,
          "wordsPerMinute": 155,
          "detectedKeywords": 8,
          "shownObjects": 5,
          "score": 82,
          "tvgSettings": null,
          "tvgSettingLevel": "DEALER",
          "isValid": true,
          "videoGradingDisabled": false,
          "videoGradingUnavailableReason": null,
          "excludedOpcode": null
        }
      ]
    }
  }
}

Response Fields

Root Level

Field	Type	Description
`statusCode`	Integer	HTTP status code
`errors`	Array	List of error objects. Empty or null on success
`warnings`	Array	List of warning objects
`inspectionToVideoGraderDetailsDTOMap`	Object	Video grader details keyed by MPI UUID. Only inspections in the requested department are returned. Absent when no inspection on the order has a graded video

Video Analysis Object (`videoAnalysisList[]`)

Field	Type	Description
`uuid`	String	UUID of the analysis
`videoGraderUuid`	String	UUID of the video grader record
`attachmentUrl`	String	URL of the graded video
`mpiUuid`	String	UUID of the inspection the video belongs to
`dealerDepartmentUUID`	String	UUID of the dealer department
`technicianIdentifiers`	Object	Technician who recorded the video
`serviceAdvisorIdentifiers`	Object	Service advisor on the order
`assessmentsByCategory`	Object	Assessment results keyed by category (see below)
`dealerIdentifiers`	Object	Dealer details
`orderIdentifiers`	Object	Order details
`inspectionTypeIdentifiersDTO`	Object	Inspection type of the MPI
`videoSentStatus`	String	Whether the video was sent to the customer
`videoViewedStatus`	Boolean	Whether the customer viewed the video
`mileage`	Integer	Vehicle mileage on the inspection
`createdOn`	Long	Creation time, epoch milliseconds
`duration`	Integer	Length of the video
`gradingDurationMillis`	Long	Time grading took from upload to results, in milliseconds
`hasProfanity`	Boolean	Whether profanity was detected
`audioQuality`	Integer	Audio quality rating
`wordCount`	Integer	Number of words spoken
`wordsPerMinute`	Integer	Speaking pace
`detectedKeywords`	Integer	Number of keywords detected
`shownObjects`	Integer	Number of vehicle components shown
`score`	Integer	Overall video score
`tvgSettings`	Object	Grading settings applied to this video
`tvgSettingLevel`	String	Level the grading settings were taken from
`isValid`	Boolean	Whether the analysis is valid
`videoGradingDisabled`	Boolean	`true` when all grading checks are turned off for this setting level
`videoGradingUnavailableReason`	String	Why grading results are unavailable; `null` for a completed analysis (see below)
`excludedOpcode`	String	The excluded opcode when grading was skipped for that reason

Assessment Item Object (`assessmentsByCategory.<category>[]`)

Field	Type	Description
`assessment`	Object	The assessment: `assessmentId`, `name`, `label`, `assessmentType` (`visual`, `boolean` or `sentiment`; it does not determine the `status` values, see below), `category` and `isAssessmentVisible`
`detections`	Array	Objects detected in the video for this assessment, with frame, timestamp, confidence and bounding box
`status`	String	Result of the assessment (see below)
`videoGraderLiteFeedbackDTOList`	Array	Feedback recorded on this assessment
`score`	Double	Score for this assessment
`isCheckDisabled`	Boolean	Whether this check is turned off in the grading settings

Possible Values

Categories (keys of assessmentsByCategory): Introduction, Vehicle Checks, Value Building, General/Overall

Assessment status: which values status can take is decided by the assessment (assessment.name), not by assessmentType:

`assessment.name`	`assessmentType`	Possible `status` values
`PRIMARY_CONCERN`, `BATTERY_TEST`, `AIR_FILTER`, `CABIN_AIR_FILTER`, `WIPER`, `HEADLIGHTS`, `BRAKES`, `TIRES`, `SUSPENSION`, `DRIVE_TRAIN`, `LEAKS`	`visual`	`Showed`, `Mentioned`, `Not Covered`, `N/A`
`INTRODUCTION`, `GREETING`, `WELCOMED`, `LICENSE_PLATE`, `TIRE_GAUGE`, `BRAKE_GAUGE`, `COMPLIMENT`, `GREEN_CHECKS_MENTIONED`, `EASY_LANGUAGE`	`boolean`	`Yes`, `No`
`PROFANITY`	`boolean`	`Yes`, `No` (`Yes` means profanity was detected, so `No` is the good result)
`PACE`	`boolean`	`Too Slow`, `Slightly Slow`, `Good`, `Slightly Fast`, `Too Fast`
`VIDEO_LENGTH`, `VIDEO_PAUSE`	`boolean`	`Green`, `Yellow`, `Red`, `N/A`

If a single check could not be graded, its status is Green, whatever the assessment.

videoGradingUnavailableReason:

IN_PROGRESS - Grading has started but results are not ready yet
SKIPPED_OPCODE - Grading was skipped because the order has an excluded opcode (see excludedOpcode)
TURNED_OFF - Grading is turned off for the inspection type
NO_AUDIO - The video has no spoken audio
AUDIO_NOT_CAPTURED - The video was recorded without audio

Response Status Codes

Status Code	Description
200	Success - video grader data retrieved
400	Bad Request - missing or invalid path parameters (`INVALID_REQUEST`)
401	Unauthorized - missing or invalid credentials
403	Forbidden - `inspection.video.grader.read` is not granted for this department
404	Not Found - the order has no inspection in this department (`ORDER_NOT_FOUND`)
500	Internal Server Error (`INTERNAL_ERROR`)

Important Notes

Key Points

Only inspections that belong to the department in the path are returned, even if the order has inspections in other departments.
An inspection appears only once a video has been uploaded for it. A video still being graded is returned with videoGradingUnavailableReason set to IN_PROGRESS.
New fields, categories, assessments and status values may be added over time. Clients must ignore fields and values they don't recognize.

How to Get Video Grader Data

Request​

HTTP Request​

Parameters​

Authorization​

Example​

Response​

Success Response (200 OK)​

Response Fields​

Root Level​

Video Analysis Object (videoAnalysisList[])​

Assessment Item Object (assessmentsByCategory.<category>[])​

Possible Values​

Response Status Codes​

Important Notes​