How to Fetch MPI Change Logs

Overview

This endpoint retrieves the complete edit history (changelog) for a specific Multi-Point Inspection (MPI). It tracks all changes made to the MPI, including field modifications, user information, and timestamps.

To use this endpoint, 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.

Endpoint Details

HTTP Method

GET

Full URL Example

https://app.mykaarma.com/scprocessor/mpi/aggregator/v1/dealerDepartment/{dealerDepartmentUUID}/multiPointInspection/{mpiUuid}/history

Authentication & Authorization

Authentication

Type	Header
Bearer Token (OAuth2)	Authorization: Bearer {access_token}

Required Scope

API Scope	Scope Level	Description
multipoint.inspection.fetch	DepartmentScope	Authorizes client to fetch MPI data and change logs

Permissions

The authenticated user must have read access to the specified dealer department and permission to fetch MPI data.

Path Parameters

Parameter	Type	Required	Description
dealerDepartmentUUID	String	Yes	Unique identifier (SHA-256 hash) for the dealer department
mpiUuid	String	Yes	Unique identifier for the Multi-Point Inspection

Request Headers

Header	Type	Required	Description
Authorization	String	Yes	Bearer token for authentication
Content-Type	String	No	application/json (default)

Response Structure

Success Response (200 OK)

{
  "statusCode": 200,
  "changes": [
    {
      "uuid": "change_log_entry_uuid",
      "mpiUuid": "Jwnok1mB0JGWd8NYNd173R27uGZN3qLPCz",
      "field": "status",
      "oldValue": "In Progress",
      "newValue": "Completed",
      "userUuid": "user_uuid_here",
      "userName": "John Doe",
      "isDateField": false,
      "change": "Status changed from 'In Progress' to 'Completed'",
      "eventTime": "2024-01-14T10:30:00.000Z",
      "statusHexCode": "#00FF00"
    },
    {
      "uuid": "change_log_entry_uuid_2",
      "mpiUuid": "Jwnok1mB0JGWd8NYNd173R27uGZN3qLPCz",
      "field": "recommendedService",
      "oldValue": "Oil Change",
      "newValue": "Oil Change, Brake Inspection",
      "userUuid": "user_uuid_here_2",
      "userName": "Jane Smith",
      "isDateField": false,
      "change": "Recommended services updated",
      "eventTime": "2024-01-14T09:15:00.000Z",
      "statusHexCode": null
    }
  ],
  "errors": [],
  "warnings": []
}

Response Fields

Root Level

Field	Type	Description
statusCode	Integer	HTTP status code (200 for success)
changes	Array	List of change log entries (chronologically ordered)
errors	Array	List of error objects (empty if successful)
warnings	Array	List of warning objects (empty if no warnings)

Change Object

Field	Type	Description
uuid	String	Unique identifier for this change log entry
mpiUuid	String	UUID of the MPI this change belongs to
field	String	Name of the field that was modified (see possible values below)
oldValue	String	Previous value of the field (null if newly created)
newValue	String	New value of the field
userUuid	String	UUID of the user who made the change
userName	String	Display name of the user who made the change
isDateField	Boolean	Indicates if this field is a date/time field
change	String	Human-readable description of the change
eventTime	String (ISO 8601)	Timestamp when the change occurred
statusHexCode	String	Hex color code associated with status changes (null for non-status fields)

Possible Field Values

The field property can have the following values:

MPI Level Changes:

• Status
• MPI Sent Status
• MPI Sent Medium
• MPI Sent Contact Info
• MPI Sent To
• Video-Only Sent Status
• Video-Only Sent Medium
• Video-Only Sent Contact Info
• Video-Only Sent To
• Order Status
• Image Count
• Video Count
• Labels

Personnel Changes:

• Assignees
• Technicians
• Parts Representative
• Service Advisor
• Parts advisors
• Labor estimate filler

Customer Interaction:

• Customer link view count
• Customer seen on

Recommendation Changes:

• Recommendations
• Recommendation status
• Recommendation Fields
• Recommendation work status
• Recommendation deleted
• Recommendation approval reason
• Recommendation approval reason note
• Recommendation Text
• Approval state

Pricing & Estimates:

• Estimate requested
• Estimate reviewer
• Estimate required
• Parts pricing
• Labor hours
• Labor Type
• Labor pricing
• Original Labor Pricing
• Original Parts Pricing
• Misc fees
• Misc fees added
• $0 Shown to Customer

Parts Management:

• Parts added
• Parts updated
• Parts removed
• Internal Parts Notes

Check & Service Details:

• Custom Check Name
• Opcode

Error Response

Error Structure

{
  "statusCode": 400,
  "changes": null,
  "errors": [
    {
      "errorCode": "INVALID_MPI_UUID",
      "errorDescription": "The provided MPI UUID is invalid or does not exist"
    }
  ],
  "warnings": []
}

Common Error Codes

HTTP Status	Error Code	Description
400	INVALID_REQUEST	Invalid request parameters
401	UNAUTHORIZED	Missing or invalid authentication token
403	FORBIDDEN	Insufficient permissions to access this resource
404	MPI_NOT_FOUND	MPI with specified UUID not found
404	DEPARTMENT_NOT_FOUND	Dealer department with specified UUID not found
500	INTERNAL_SERVER_ERROR	Server encountered an unexpected error

Example Request

cURL

curl -X GET \
  'https://app.mykaarma.com/scprocessor/mpi/aggregator/v1/dealerDepartment/{dealerDepartmentUUID}/multiPointInspection/{mpiUuid}/history' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Response Status Codes

Status Code	Description
200	Success - MPI change log retrieved successfully
400	Bad Request - Invalid parameters or malformed request
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - MPI or department not found
500	Internal Server Error - Server-side error occurred

Use Cases

Audit Trail

Track all modifications made to an MPI for compliance and auditing purposes.

User Activity

Monitor which users made changes and when.

Dispute Resolution

Verify what changes were made and by whom in case of disputes.

Compliance Reporting

Generate reports showing the complete history of inspection modifications.

Rollback Reference

Use historical data to understand previous states of the inspection.

Important Notes

Key Points

• The changes array is ordered chronologically, with the most recent changes first
• The isDateField flag helps clients format date values appropriately in the UI
• The statusHexCode field is only populated for status-related changes and contains the color code for visual representation
• Empty errors and warnings arrays indicate a successful operation with no issues
• The eventTime field follows ISO 8601 format and is in UTC timezone