MindTickle Upgrade & Migration

Overview

MindTickle is a sales enablement and readiness platform with APIs for managing courses, quizzes, user progress, and coaching sessions. The API exposes endpoints for content management, learner analytics, and CRM integration. Tracking API changes is essential because MindTickle evolves its content schema (course structures, quiz question types, scoring rubrics), user progress tracking fields, and SSO/SCIM provisioning models — breaking integrations that sync training completion data to Salesforce or automate onboarding workflows.

Version Detection

const MINDTICKLE_BASE = "https://api.mindtickle.com/v2";

async function detectMindTickleVersion(apiKey: string): Promise<void> {
  const res = await fetch(`${MINDTICKLE_BASE}/users`, {
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  });
  const version = res.headers.get("x-mt-api-version") ?? "v2";
  console.log(`MindTickle API version: ${version}`);

  // Check for deprecated course fields
  const coursesRes = await fetch(`${MINDTICKLE_BASE}/courses?limit=1`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const data = await coursesRes.json();
  const knownFields = ["id", "title", "modules", "status", "created_at", "assigned_users"];
  if (data.courses?.[0]) {
    const actual = Object.keys(data.courses[0]);
    const newFields = actual.filter((f) => !knownFields.includes(f));
    if (newFields.length) console.log(`New course fields: ${newFields.join(", ")}`);
  }
}

Migration Checklist

Review MindTickle release notes for API schema changes
Audit codebase for hardcoded course status enums (
```
draft
```
,
```
published
```
,
```
archived
```
)
Verify quiz question type support — new types may require parser updates
Check user progress response for new completion metric fields
Update SCIM provisioning payload if user attribute schema changed
Test coaching session API for new rubric scoring fields
Validate CRM sync field mappings (Salesforce/HubSpot) after API update
Check if module ordering mechanism changed (position vs. sort_order)
Update webhook handlers for course completion and quiz score events
Run learner analytics export to verify report format compatibility

Schema Migration

// MindTickle course progress: flat completion → structured module-level tracking
interface OldProgress {
  user_id: string;
  course_id: string;
  completed: boolean;
  score: number;
  completed_at?: string;
}

interface NewProgress {
  user_id: string;
  course_id: string;
  status: "not_started" | "in_progress" | "completed" | "expired";
  overall_score: number;
  modules: Array<{
    module_id: string;
    status: string;
    score: number;
    attempts: number;
    time_spent_seconds: number;
  }>;
  certifications: Array<{ cert_id: string; issued_at: string; expires_at?: string }>;
  completed_at?: string;
}

function migrateProgress(old: OldProgress): NewProgress {
  return {
    user_id: old.user_id,
    course_id: old.course_id,
    status: old.completed ? "completed" : "not_started",
    overall_score: old.score,
    modules: [],
    certifications: [],
    completed_at: old.completed_at,
  };
}

Rollback Strategy

class MindTickleClient {
  private apiVersion: "v1" | "v2";

  constructor(private apiKey: string, version: "v1" | "v2" = "v2") {
    this.apiVersion = version;
  }

  async getCourses(limit = 50): Promise<any> {
    try {
      const res = await fetch(`https://api.mindtickle.com/${this.apiVersion}/courses?limit=${limit}`, {
        headers: { Authorization: `Bearer ${this.apiKey}` },
      });
      if (!res.ok) throw new Error(`MindTickle ${res.status}`);
      return await res.json();
    } catch (err) {
      if (this.apiVersion === "v2") {
        console.warn("Falling back to MindTickle API v1");
        this.apiVersion = "v1";
        return this.getCourses(limit);
      }
      throw err;
    }
  }
}

Error Handling

Migration Issue	Symptom	Fix
Course status enum expanded	`400` creating course with unrecognized status value	Fetch valid statuses from `/courses/statuses` endpoint
Quiz question type unsupported	Quiz import fails with `unknown_question_type`	Add parser support for new question types (drag-drop, hotspot)
SCIM attribute renamed	User provisioning fails with `invalid attribute`	Update SCIM payload to match current user schema from `/schemas`
Progress field restructured	Code crashes accessing `progress.completed` (now `progress.status` )	Update to check `status === "completed"` instead of boolean
Webhook signature algorithm changed	Webhook verification fails on all events	Update HMAC verification to use new algorithm from MindTickle docs

Resources

Next Steps

For CI pipeline integration, see

mindtickle-ci-integration

Claude-code-plugins mindtickle-upgrade-migration