Integration Guide Validation Pilot Proposal Data & Compliance ROI Model

Technical Integration Guide

Connect your platform to QLM in 3 API calls. From question bank to personalized assessment in under an hour.

Overview

QLM is a question selection engine that sits between your item bank and your learners. You send us your questions and a learner profile. We return the best questions to ask next, based on what will produce the most precise measurement of that learner's ability in the fewest items. Your platform stays in control of the experience — we optimize which questions get served and when.

Prerequisites

  • ✓API Key — Sandbox keys are free and available immediately. Production keys require a signed agreement.
  • ✓HTTPS — All API communication is encrypted. HTTP requests are rejected.
  • ✓JSON — All requests and responses use Content-Type: application/json.
  • ✓Item Bank — At minimum, 5 questions in the format described below. Recommended: 50+ for meaningful selection.

Question Bank Format

This is the most important section. Your item bank is the foundation of everything QLM does. The better your item metadata, the faster the engine calibrates and the more precise the measurement.

Minimum Viable Item

The simplest item that QLM can work with:

JSON — Minimum Item
{
  "item_id": "CALC-101-Q42",           // Your unique identifier
  "stem": "What is the derivative of f(x) = 3x² + 2x - 1?",
  "options": ["6x + 2", "3x + 2", "6x² + 2", "6x - 1"],
  "correct_index": 0,                   // 0-based index
  "difficulty": 0.5,                     // 0.0 (easy) to 1.0 (hard), or null for auto-calibration
  "domain": "calculus",                  // Your domain taxonomy
  "skill_id": "derivatives_polynomial",  // Your skill taxonomy
  "discrimination": null,                // null = let QLM calibrate from responses
  "content_tags": ["math", "calculus", "derivatives"]
}

Full Item Schema

All available fields, including optional metadata that improves selection quality:

JSON — Full Item Schema
{
  "item_id": "string (required)",
  "stem": "string (required) — the question text",
  "options": ["string", "string", "string", "string"] // required for multiple choice,
  "correct_index": "int (required) — 0-based",
  "difficulty": "float 0.0-1.0 (optional) — null for auto-calibration",
  "discrimination": "float 0.2-5.0 (optional) — null for auto-calibration",
  "domain": "string (required) — your top-level category",
  "skill_id": "string (optional) — granular skill within domain",
  "content_tags": ["string"] // optional,
  "passage": "string (optional) — stimulus text for reading comprehension",
  "explanation": "string (optional) — shown after answering",
  "blooms_level": "int 1-6 (optional) — Bloom's taxonomy level",
  "estimated_time_seconds": "int (optional)",
  "prerequisites": ["skill_id"] // optional — skills that should be mastered first
}

Bulk Upload Formats

You can upload your item bank in any of these formats:

JSON Array Array of item objects in a single file
CSV Columns matching the schema fields
JSONL One JSON item object per line
1

API Call 1: Optimize

Select the right questions for a specific learner. Send us the learner profile and your candidate item pool, and we return the optimal items ranked by expected measurement value.

HTTP Request
POST /v1/optimize
X-API-Key: your-api-key
Content-Type: application/json

Request Body

JSON — Optimize Request
{
  "domain": "mathematics",                    // REQUIRED: top-level domain
  "learner": {                                // REQUIRED: who is being assessed
    "learner_id": "student-42",               // REQUIRED: your unique student ID
    "ability_estimate": 0.0,                  // OPTIONAL: prior ability (-3 to +3 scale, 0 = average)
    "response_history": [],                   // OPTIONAL: recent item_ids answered
    "mastery_profile": {                      // OPTIONAL: per-skill mastery (0.0-1.0)
      "derivatives_polynomial": 0.8,
      "integration_basic": 0.3
    }
  },
  "candidate_items": [                        // REQUIRED: your item pool (5-500 items)
    {
      "item_id": "CALC-101-Q42",
      "difficulty": 0.5,
      "domain": "mathematics",
      "content_tags": ["calculus", "derivatives"],
      "discrimination": 1.0,                  // OPTIONAL
      "skill_id": "derivatives_polynomial"    // OPTIONAL
    }
  ],
  "num_select": 5,                            // REQUIRED: how many items to select (1-50)
  "objective": "accuracy",                    // OPTIONAL: "accuracy" | "speed" | "balanced"
  "constraints": {}                           // OPTIONAL: custom constraints
}

Response

JSON — Optimize Response
{
  "job_id": "opt_a8f3c2e1...",
  "status": "completed",
  "selected_items": [
    {"item_id": "CALC-101-Q42", "rank": 1},
    {"item_id": "CALC-101-Q17", "rank": 2}
  ],
  "confidence": 0.87,
  "timestamp": "2026-04-08T14:32:00Z",
  "engine_version": "1.0.0"
}
2

API Call 2: Submit Response

After the learner answers a question, submit the result. The engine updates its ability estimate and returns the next recommended items.

HTTP Request
POST /v1/sessions/{session_id}/responses
X-API-Key: your-api-key
Content-Type: application/json

Request Body

JSON — Submit Response
{
  "item_id": "CALC-101-Q42",
  "response": 1,              // 1 = correct, 0 = incorrect
  "time_ms": 45000,           // OPTIONAL: response time in milliseconds
  "used_hint": false,         // OPTIONAL: whether the learner used a hint
  "answer_changes": 0         // OPTIONAL: number of times the answer was changed
}

Response

JSON — Submit Response Result
{
  "next_items": [{"item_id": "CALC-101-Q89"}],
  "state": {
    "estimates": {"calculus": 0.65}
  },
  "confidence": {
    "level": 0.72,
    "reached": false
  },
  "engine_version": "1.0.0"
}
3

API Call 3: Get Calibration Insights

As learners interact with your items, QLM continuously calibrates item parameters. This endpoint shows how your items are improving over time.

HTTP Request
GET /v1/optimization/insights
X-API-Key: your-api-key

Response (excerpt)

JSON — Calibration Insights
{
  "total_items": 247,
  "calibrated_items": 198,
  "pending_calibration": 49,
  "item_improvements": [
    {
      "item_id": "CALC-101-Q42",
      "original_difficulty": 0.5,
      "calibrated_difficulty": 0.62,
      "discrimination": 1.34,
      "responses_analyzed": 412,
      "stability": "stable"
    },
    {
      "item_id": "CALC-101-Q17",
      "original_difficulty": 0.7,
      "calibrated_difficulty": 0.45,
      "discrimination": 0.89,
      "responses_analyzed": 287,
      "stability": "calibrating",
      "flag": "difficulty_mismatch"
    }
  ],
  "summary": {
    "avg_difficulty_shift": 0.12,
    "items_flagged": 8,
    "measurement_precision_improvement": "23%"
  },
  "engine_version": "1.0.0"
}

Next Steps

Step Action Timeline
1. Sandbox Access Request a free sandbox API key to test with your own item bank Same day
2. Run a Pilot First 10,000 assessments are free. See our Pilot Proposal for details. 1-2 weeks
3. Review Validation See our psychometric validation results on published datasets Self-service
4. Contact Sales For production contracts, volume pricing, and enterprise SLAs Schedule a call

Ready to Get Started?

Request a free sandbox API key and test QLM with your own item bank today.

Request Sandbox Access