Paperscorer Core API Guide

Paperscorer Learnosity API Guide

Paperscorer is technology that generates print answer sheets/forms and automatically captures scores entered by users via mobile devices or standard scanners. Captured scores or images can then be sent back to external systems. These web services outline how to integrate Paperscorer technology with your Learnosity service. This API is meant to be used in conjunction with the Paperscorer Core API.

POST getActivityList

Returns a list of all active Learnosity activities for a client

Required Headers:

clientEmail (string) - The email / client ID associated with your Paperscorer account. This will be provided to you by Paperscorer during onboarding.
consumerKey (string) - The Learnosity consumer key created for Paperscorer transactions within your Learnosity account.
secretKey (string) - The Learnosity secret key created for Paperscorer transactions within your Learnosity account.
clientDomain (string) - The domain associated with your Paperscorer account. This will be provided to you by Paperscorer during onboarding.

Post getItemList

Returns all items associated with the Learnosity client.

Required Headers:

clientEmail (string) - The email / client ID associated with your Paperscorer account. This will be provided to you by Paperscorer during onboarding.
consumerKey (string) - The Learnosity consumer key created for Paperscorer transactions within your Learnosity account.
secretKey (string) - The Learnosity secret key created for Paperscorer transactions within your Learnosity account.
clientDomain (string) - The domain associated with your Paperscorer account. This will be provided to you by Paperscorer during onboarding.

GET getItemListbyOrganisationId

Returns all items associated with a specific organization ID within a given Learnosity instance.

Required Headers:

clientEmail (string) - The email / client ID associated with your Paperscorer account. This will be provided to you by Paperscorer during onboarding.
consumerKey (string) - The Learnosity consumer key created for Paperscorer transactions within your Learnosity account.
secretKey (string) - The Learnosity secret key created for Paperscorer transactions within your Learnosity account.
clientDomain (string) - The domain associated with your Paperscorer account. This will be provided to you by Paperscorer during onboarding.

Body:

organizationId (string) - the Learnosity organizationId

GET getAnswersheetJsonForActivity

Given a Learnosity Activity ID, automatically transforms the activity into Paperscorer JSON,

Required Headers:

clientEmail (string) - The email / client ID associated with your Paperscorer account. This will be provided to you by Paperscorer during onboarding.
consumerKey (string) - The Learnosity consumer key created for Paperscorer transactions within your Learnosity account.
secretKey (string) - The Learnosity secret key created for Paperscorer transactions within your Learnosity account.
clientDomain (string) - The domain associated with your Paperscorer account. This will be provided to you by Paperscorer during onboarding.

Body:

organizationId (string) - the Learnosity organizationId

GET generateQuestionPaper

Generates a printable HTML version of the questions in the assessment without answers.

Parameters:

userId (int) - The unique identifier used when generating the form using the saveTask API
institutionId (int) - (optional) The unique institution identifier returned in the userLogin API.
clientType (string) - Paperscorer will provide this value to you when during onboarding.
json (Json) - Contains json object as explained below:
- assessment_name (String) - The name of the assessment. This will appear on the printable form.
- questions (array)
  - content (string) - the stem of the question.
  - text (string) - the sequencing string to be used for each question (e.g. 1, 1a, 2, 2a)
  - type (int) - the question type.
    - 1 for single option
    - 2 for multi-option
    - 3 for numeric
    - 4 for true/false
    - 5 for matching
    - 6 for ordering
    - 9 for essay
  - answers (array)
    - content (string) - the answer option
    - text (string) - the sequencing string to be used for each answer (e.g. a, b, c, d; T, F)
  - features (array) - (optional) - Typically used for passages. If this is provided, the string will be presented before the question.
    - content (string) - content of passage.
    - heading (string) - the heading of the passage.

Request Headers:
Authorization token returned from the userLogin API.

GET getAllQuestionsStudentResponse

Returns the detailed results of a student submission for a given form.

Parameters:

formId (int) - the formID returned from the saveTask API.
studentId (int) - (optional) The unique Paperscorer student identifier provided for a given student. Returned in the getAssessmentStudents API.
pageNo (int) - The number of pages in the form.
externalFormId (String) - The id of assessment in your system. This should be correlated to the formID returned from saveTask within your system.

Response Metadata:

assessmentName (String) - The name of the assessment sent to the saveTask API.
email (string) - The email ID sent to the saveTask API
questions (object) - Contains key-value pairs below:
- questionID
  - answerID - the unique Paperscorer ID for the answer
  - text - the sequence string used for the answer (e.g., A, B, C, D; T, F)
  - isCorrect - 1 if student answered the question correctly; 0 if student answered the question incorrectly.
  - isAttempt - 1 if student attempted the question; 0 if the student left the answer blank.
  - externalAnswerID - the unique ID for the answer sent to the saveTask API
  - questionID - the unique Paperscorer ID for the question
  - questionType - the type of the question
  - questionText - the sequence string used for the question (e.g., 1, 1a, 2, 2a)
  - isMultiAttemptError - true if the form has been submitted multiple times
  - isPartialError - true if an error was encountered because the value was partially filled by the student
  - markedAnswerText - if the questionType is numeric (3), the numeric value entered by the student.
  - isQuestionIdValid - true or false
  - isQuestionTypeValid - true or false

Request Headers:
Authorization token returned from the userLogin API.

GET getAssessmentStudents

Returns a list of students associated with a given form generated from the saveTask API.

Parameters:

externalFormId (String) - The id of assessment in your system. This should be correlated to the formID returned from saveTask within your system.
showAll (boolean) - True returns all students assigned to a form even if the form has been edited/changed. False returns only the students for the active (latest version) form.
institutionId (int) - The unique institution identifier returned in the userLogin API.

Request Headers:
Authorization token returned from the userLogin API.

GET getProcessedFormIds

Returns the status of an answer sheet processing job that was submitted via the submitAnswersheetProcessingJob API.

Parameters:

userId (int) - The unique identifier used when generating the form using the saveTask API
institutionId (int) - The unique institution identifier returned in the userLogin API.
JobId (int) - Asynchronous job submission id returned by the submitAnswersheetProcessingJob API response.

Response Metadata:

jobId - The asynchronous job submission id.
totalImages - The total individual answer sheets extracted from the PDF or Image submitted to the submitAnswersheetProcessingJob API.
processedImages - The total number of answer sheets processed to-date.
statusDetails - Array indicating the status of each of the processed answer sheets.
formIds - Array of formIDs (returned from saveTask API) that have been processed to-date.
clientAssessmentIds - Array of client assessment id's (sent to saveTask API form your system) that have been processed to-date.
isJobComplete - Boolean representing whether the entire job is complete.
message - A message indicating the status of the job.
status - API status, 1 in case of success and 0 in case of failure.

Request Headers:
Authorization token returned from the userLogin API.

GET getScoredStudentDetails

Returns details of all students and overall scores for a given assessment.

Parameters:

institutionId (int) - The unique institution identifier returned in the userLogin API.
formId (string) - The form ID returned from the the saveTask API.
clientType (string) - Paperscorer will provide this value to you when during onboarding.

Request Headers:
Authorization token returned from the userLogin API.

GET getScoresByFormId

Provides detail of every student associated with a form. Used for syncing data to external systems.

Parameters:

formId (string) - The form ID returned from the the saveTask API.
domain (string) - domain to which the user belongs. Returned from userLogin API
email (string) - email id of user who is generating the answer sheet. Returned from userLogin API.
clientId (int) - unique client ID within Paperscorer. Returned from userLogin API.
offset (int) - used to return student detail in pages.

Response Metadata:

formID - The form ID returned from the the saveTask API.
studentID - The unique Paperscorer student identifier provided for a given student. Returned in the getAssessmentStudents API.
imageURL - The URL of the scanned and scored answer sheet.
scoreTime - The time at which the sheet was scored.
ImageUrls - array of ??
questions - object of all questions submitted by the student.
- answerID - the unique Paperscorer ID for the answer
- text - the sequence string used for the answer (e.g., A, B, C, D; T, F)
- isCorrect - 1 if student answered the question correctly; 0 if student answered the question incorrectly.
- isMarked - 1 if the student marked this answer; 0 if this answer is not marked.
- isAttempt - 1 if student attempted the question; 0 if the student left the answer blank.
- externalAnswerID - the unique ID for the answer sent to the saveTask API
- questionID - the unique Paperscorer ID for the question
- questionType - the type of the question
- questionText - the sequence string used for the question (e.g., 1, 1a, 2, 2a)
- isMultiAttemptError - true if the form has been submitted multiple times
- isPartialError - true if an error was encountered because the value was partially filled by the student
- markedAnswerText - if the questionType is numeric (3), the numeric value entered by the student.
- quesMetaData - ???
- ansMetaData - ?/?

Request Headers:
Authorization token returned from the userLogin API.

GET getStudentDetails

Returns all assessment scores and details for a given student.

Parameters:

userId (int) - The unique identifier used when generating the form using the saveTask API
institutionId (int) - The unique institution identifier returned in the userLogin API.
studentId - The unique Paperscorer student identifier provided for a given student. Returned in the getAssessmentStudents API. .
clientType (string) - Paperscorer will provide this value to you when during onboarding.

Request Headers:
Authorization token returned from the userLogin API.

GET getTaskStatus

Returns the status of an answer sheet generated from the saveTask API as well as details related to the answer sheet, such as answer sheet urls, and formIds.

Parameters:

taskId (int) - The taskID returned from the saveTask API
userId (int) - The unique identifier used when generating the form using the saveTask API
institutionId (int) - The unique institution identifier returned in the userLogin API.

Request Headers:
Authorization token returned from userLogin API.

GET getUploadedErrorImageDetails

Returns all erroneous answer sheets with details of errors for each.

Parameters:

tokenId (string) - The token generated from userLogin API
platform - (string) - The platform value returned from userLoginAPI
showTokenDetails - (string) - Should be set to false.
userId (int) - The unique identifier used when generating the form using the saveTask API.
institution_id (integer) - unique identifier for the institution generating the answer sheet. Returned from userLogin API.

Response Metadata:

Sheets as key with the below values:
- image_url - The URL of the scanned sheet on which errors were found.
- student_id - The unique Paperscorer student ID assigned to the student by the saveTask API.
- form_id - The form ID associated to the form by the saveTask API.
- page_number - The page on which the error was found.
- task_id - A unique ID assigned to this answer sheet.
- institution_id - unique identifier for the institution generating the answer sheet. Returned from userLogin API.
- user_id - The unique identifier used when generating the form using the saveTask API.
- errorType - The type of error occurred
- errorMessage - The message related to the error(s).
- externalFormId -The assessment ID from your system sent to the saveTask API.
- image_name - The name of the image where error was found, e.g. page 1.
- student_name - The student name sent to the saveTask API for the student associated with the erroneous sheet.
- htmlErrorMessage - A version of the error message in HTML format.

Request Headers:
Authorization token returned from userLogin API.

GET getUserAssessments

Returns a list of all forms associated with a given user.

Parameters:

userId (int) - The unique identifier used when generating the form using the saveTask API.
institution_id (integer) - unique identifier for the institution generating the answer sheet. Returned from userLogin API.
clientType (string) - Paperscorer will provide this value to you when during onboarding.

Response Metadata:

name - The assessment name sent to the saveTask API.
form_id - The unique formID returned by the saveTask API.
external_aid - The assessment ID from your system sent to the saveTask API.
total_pages - The total number of pages
date_created - The date at which the form was created.

Request Headers:
Authorization token returned from userLogin API.

GET getStudentListsPerAssessment

Returns an array of student names, emails, external Student IDs, and scores (if applicable) that have been associated with an assessment through the saveTask API.

Query Params:

formId (string) - The form ID returned from the the saveTask API.
clientType (string) - Paperscorer will provide this value to you when during onboarding.

Request Headers:
Authorization token returned from userLogin API.

POST saveTask

Generates an answer sheet for a given assessment and array of students.

Request Metadata:

email (String) - email id of user who is generating the answer sheet. Returned from userLogin API.
institution_id (integer) - unique identifier for the institution generating the answer sheet. Returned from userLogin API.
domain_name (String) - domain to which the user belongs. Returned from userLogin API
clientType (string) - Paperscorer will provide this value to you when during onboarding.
status (String) - "ready" - signifies it is ready to be processed
threadCall (String) - if true, then sheet generation will be done in a separate thread.
json (Json) - contains json object as explained below:
- question_text_available (integer) - 0 or 1, if 1 then 'text' field in question array will be used as an identifier for each item in the answer sheet. E.g., 1., 2a, 1.2.1a, etc.
- scorerGrader (integer) - 0 sent in case of google, kept for future purpose
- assessment_name (String) - the name of the assessment. This will appear in the header of the generated answer sheet.
- ltst (String) - description of the assessment.
- templateId (integer) - Unique template to use in generating the answer sheet This can be customized. Use 0 for an answer sheet with a pre-filled student ID. Use 1 for an answer sheet that allows students to bubble in their unique student ID.
- assessment_id (String) - The id of assessment in your system. This should be correlated to the formID returned from saveTask within your system.
- saveEssayImage (optional)(String) - If "true", then individual images will be captured for all essay responses during scanning and saved for retrieval via the essayImageDetails API
- max_score (integer) - maximum score one can receive on the assessment. This is only used when Paperscorer is calculating scores for your sustem.
- students (array) - the students for which answer sheets should be generated. Contains below fields:
  - name (String) - name of student
  - identifier (String) - email id or other recognizable identifier of the student
  - id (String) - unique identifier of the student within your system.
- questions (array) - the individual items in your assessment. Contains below fields:
  - text - sequencing of the questions e.g. 1,2,3 etc
  - type (integer)
    - 1 - single option multiple choice
    - 2 - multiple select multiple choice
    - 3 - numeric
    - 9 - Essay
  - qid - unique question id from your system.
  - essayPageArea (optional)(String) - if type is 9, integer value in string represents the percentage of the page area that the essay question should consume.
    - "12.5" for an eight of the page
    - "25" for a quarter of the page
    - "50" for a half of the page
    - "75" for three quarters of the page
    - "100" for the entire page
    - 125 for 1 and 1 quarter pages
    - 150 for 1 and a half pages
    - etc.
  - essayLineHeight (optional)(String) - if type is 9, "EXTRA_SPACE" for 30pt value and "STANDARD" for 20pt value Default value "STANDARD". For no lines, use "NONE"
  - answers (array) - contains below fields:
    - pointValue (double) - half marking of multi answer questions
    - ansid - unique id of the answer from your system
    - text - sequencing A, B, C; T, F; etc
    - isCorrect (integer) - 0 for false and 1 for true

Request Headers:
Authorization token returned from userLogin API.

POST skipImage

Results in a specific answer sheet being removed from the queue for scoring.

Parameters:

taskId (int) - A unique id assigned to every scanned/uploaded answer sheet. Returned by scanUploadedSheet API or errorSheets API.

Request Headers:
Authorization token returned from userLogin API.

POST submitAnswersheetProcessingJob

Accepts a single PDF with one or more answer sheets OR a single answer sheet image file in JPEG, JPG or PNG format and then processes and grades them. Once the file is read successfully, the rest of the processing is done as an asynchronous job. The API returns back a jobId. This jobId can be used to track the processing progress using the getProcessedFormIds API.

Request Metadata:

file (InputStream) - The file to be uploaded. Must be PDF, JPEG, JPG or PNG format.
isPDFCall (String) - Indicates whether the uploaded file is a PDF.
clientType (string) - Paperscorer will provide this value to you when during onboarding.
fileDetail (Json String) - contains below fields:
- userId (integer) - the userID associated with the assessment. This should be the same userID used when the answer sheet was generated using the saveTask API.
- institution_id (int) - The unique ID for the client, returned by the userLogin API.
- fileName (String) - The name of the file to be uploaded.
- platform (String) - The platform from which it is logging web/mobile/email.
- isAutoSyncEnabled (Boolean) - Optional field, to indicate if auto sync is enable. This is typically false.

Response Metadata:

jobId - a unique ID representing the asynchronous job of this scanning process.
totalImages - The total sheets extracted from uploaded file.
fileName - The name of the uploaded file.
message - A message indicating success or failure. If the job submission fails, this message will provide details.
status - 1 in case of success and 0 in case of failure.

Request Headers:
Authorization token returned from userLogin API.

POST Token

API for authorization on all other APIs. This is the first API that should be called for any session. After receiving a token, you should use the token to call the userLogin API, which creates a token for a specific user in your system.

Required Inputs:

client_id (string) - a client ID that will be provided to you by Paperscorer during onboarding.
client_secret (string) - a client secret that will be provided to you by Paperscorer during onboarding.
grant_type - (string) a string that will be provided to you by Paperscorer during onboarding.

Request Headers:
None.

POST userLogin

Authenticates a specific user within your system. This should be the second API called after Token. This ensures that all answer sheets and student scores are associated with the correct user. It is recommended that the Access Token, Institution_id, platforms, and user_id be saved in session to use in subsequent APIs.

Request Metadata:

domain (string) - domain to which the user belongs. Returned from userLogin API
clientId (int) - The unique client ID within Paperscorer. Returned from userLogin API.
first_name (String) - The first name of the user.
last_name (String) - The last name of the user.
email (String) - email id of user, e.g. testaccount@paperscorer.com
is_active (String) - (optional) 1 for true and 0 for false i.e. user is active or not. If not passed, default value 1 is used
is_student (String) - (optional) 1 for true and 0 for false i.e. user is student or teacher. If not passed, default value 0 is used
deviceId (alphanumeric) - (optional) device id of user.
platform (String) - (optional) platform from which API is accessed e.g. web/mobile/email

Response Metadata:

ResponseCode - Indicates whether the user was successfully logged in or not. 1 for success; 0 for failure.
Access Token - access token generated for all subsequent API calls.
Refresh Token - sent as blank, kept for future purpose to refresh oauth token.
message - A message indicating whether the login was successful.
institution_id - The unique identifier for a client.
platforms - The patform from which user logged in e.g. Android
Scope - The scope of authentication
user_id - The unique user identifier.
license_id - The license id given to user.
is_new_user - Indicates whether this is the first time the user has logged in to Paperscorer.
user_license_type - The type of license assigned to the user.
Token Type - The type of token granted to the user.
showExpiryAlert - Used for Papersorer internal purposes.
Expiry - The expiry for the logged in user.
Status - 1 in case of success and 0 in case of failure.

Request Headers:
Authorization token returned from Token API.