Learnosity-PaperScorer API
Specialized API documentation for integrating PaperScorer's advanced printing and scanning capabilities into your Learnosity assessment platform. Works alongside the PaperScorer Core API.
Overview
The Learnosity-PaperScorer API enables seamless integration between PaperScorer's paper-based assessment capabilities and your Learnosity platform. Generate answer sheets directly from Learnosity Items or Activities, and sync scores back to Learnosity sessions for unified reporting.
Base URL
https://learnosity.paperscorer.comSupported Learnosity Item Types
PaperScorer can convert the following Learnosity item types to paper assessment sheets
Multiple Choice
Standard and block layout formats
Multiple Choice (Multiple Response)
Select all that apply questions
True or False
Binary response questions
Math (Fill in the Blanks)
Numeric response questions
Cloze Math
Mathematical fill-in questions
Match List
Matching questions
Order List
Sequencing questions
Sort List
Categorization questions
Gridded
Grid-based numeric responses
Essay (Rich Text)
Long-form written responses
Essay (Plain Text)
Plain text responses
Short Text
Brief written responses
More question types coming soon
Multi-Version Assessments
Generate N distinct printed variants of the same Learnosity activity. Each variant shuffles question order and per-question option order, so two students sitting next to each other can't easily share answers. All variants score against the same canonical Learnosity validation — no separate answer keys to maintain. The engine identifies the variant at scan time, reverses the shuffle map, and emits responses in canonical terms, so scan and sync stay version-agnostic.
Multi-version generation is available today through the PaperScorer dashboard. Public API support for the versions parameter on sheet generation endpoints is available on request — contact support@paperscorer.com.
Integration Workflow
Follow these steps to integrate PaperScorer with your Learnosity platform
Authentication
Authentication is handled automatically on every Learnosity API request — no separate login call is required. Each request must include three required headers that identify the client and the Learnosity itembank to read from.
- Client-Id and Client-Domain are issued by PaperScorer when your account is provisioned.
- Consumer-Key is the Learnosity consumer key for the itembank PaperScorer should read from.
- These headers are sent on every request. There is no token to refresh and no separate authentication endpoint to call.
Required Headers
<your-client-id><your-client-domain><learnosity-consumer-key>Discover Activities & Items
Before generating sheets, list the Learnosity activities and items PaperScorer can read. These endpoints are the entry point for any workflow that drives off Learnosity content.
- Get Activity List returns every Learnosity activity available in the configured itembank.
- Get Item List returns items by activity or by direct item reference for finer-grained selection.
- Get Item List By Organisation ID scopes item lookup to a specific organisation when the itembank is multi-tenant.
Relevant Endpoints
/api/get-activity-list/api/get-item-list/api/get-item-list-by-organisation-idAnswer & Question Sheet Generation
Generate the printable bubble sheet (PDF) and the readable question paper (HTML) from a Learnosity activity, a set of items, or every item under an organisation. JSON variants are available when you want the underlying sheet model instead of a rendered file.
- Answer sheets return a PDF URL that can be printed and distributed to students. Each sheet receives a Form ID for later score retrieval.
- Question sheets return an HTML URL containing the readable question paper that pairs with the answer sheet.
- JSON variants return the same sheet model as structured data — useful when you want to render the sheet yourself or audit its contents.
- Supports multiple Learnosity item types including multiple choice, true/false, and more.
Relevant Endpoints
/api/get-answer-sheet-pdf-for-activity/api/get-answer-sheet-pdf-by-item/api/get-answer-sheet-pdf-by-organisation-id/api/get-answer-sheet-json-for-activity/api/get-question-sheet-html-for-activity/api/get-question-sheet-html-by-item/api/get-question-sheet-html-by-organisation-id/api/get-question-sheet-json-for-activityScanning & Processing
Students complete their assessments on paper. Three submission methods are available for processing completed answer sheets.
- Mobile App: Scan sheets using the free PaperScorer iOS or Android app
- Email: Scan and email sheets directly to PaperScorer for processing
- Platform Upload: Send scanned PDFs or images to /api/upload-pdf. Multi-page uploads return one task_id per page.
- Poll /api/get-job-status for the rolled-up job state, or /api/get-task-status to check each task_id individually.
Relevant Endpoints
Score Retrieval
Once processing is complete, retrieve Learnosity session IDs for the processed form IDs and sync scores back into your Learnosity platform for unified reporting.
- Use /api/get-session-ids-from-form-id to map processed PaperScorer form IDs back to their Learnosity session IDs.
- Use /api/sync-student-scores to sync captured scores back into Learnosity. If a student does not yet exist in Learnosity, a new testing session is created automatically.
- Supports both push (callback) and pull (polling) retrieval methods.
Relevant Endpoints
/api/get-session-ids-from-form-id/api/sync-student-scoresError Correction
Some scanned sheets get flagged — a student ID the engine could not match, a question with multiple bubbles marked, or a partial fill. Resolve them with a drop-in JavaScript embed that talks to two server-side endpoints; corrected scores flow into Learnosity through the same auto-sync path as a fresh scan.
- Drop the correction embed into your app with a data-ps-correction-embed div and correction.js — a live demo is available to preview the embed in action. View corrections embed demo.
- Your backend brokers /api/get-correction-sheet (fetch the sheet image, bubbles, and engine flags) and /api/submit-correction-sheet (post the teacher's corrections), keeping your Consumer-Key off the browser.
- On submit, the sheet is reprocessed and the corrected scores are ready to be re-synced into Learnosity via /api/sync-student-scores — or pushed automatically to your callback URL if one is configured.
Relevant Endpoints
/api/get-correction-sheet/api/submit-correction-sheet/api/sync-student-scoresSecure Data Handling
All responses from the PaperScorer engine are encrypted with a key that is shared with our development partners for decryption. This ensures student data remains protected throughout the integration.
Secure authentication
Header-based authentication via Client-Id, Client-Domain, and Consumer-Key headers
FERPA-aligned student data handling
Built to support FERPA-aligned handling of student educational records and personally identifiable information.
Rate limiting
Per-client throttling on PDF generation and score import endpoints to prevent abuse and protect uptime.
Data encryption
Sensitive response payloads are encrypted with a partner-shared key, in addition to TLS in transit.
Data decryption library
Sample decryption libraries in PHP and Java to integrate with the encrypted payload format.
// Example: Creating an answer sheet PDF for a Learnosity activity
POST /api/get-answer-sheet-pdf-for-activity
{
"activity_id": "Test_Activity",
"activity_title": "Math Algebra Test",
"students": [
{
"name": "Jane Doe",
"identifier": "student1@mail.com",
"id": "stu_001"
}
]
}
// Response
{
"success": true,
"data": {
"response": {
"pdf_url": "http://forms.paperscorer.com/forms/10/444/1554/10593_438240.pdf",
"html_url": "",
"total_pages": 1,
"form_id": 10593,
"task_id": 88510,
"activity_id": "Test_Activity",
"activity_template_id": "Test_Activity_Template",
"activity_title": "Math Algebra Test"
}
},
"message": "Answer sheet created successfully.",
"errors": []
}Get Started for Free
You can create a free account with no obligation to purchase. Scan up to 100 testing sheets completely free while you test your Learnosity integration.