Paperscorer Core API Help

The Paperscorer Core API enables institutions to include advanced printing and scanning capabilities into their platforms.  Core API functionality can be found at the following link.  

Authentication

Regardless of the Paperscorer process, the first step is to provide authentication as an API partner (oAuthoToken) and then to login to Paperscorer on behalf of the educator who is using your system (userLogin).  If this is the first time that the educator has been logged into Paperscorer, we will create a new account.  After login, session information will be returned by Paperscorer, which can then be used in subsequent calls to the Paperscorer API. 

Endpoints Used The following workflow describes the authentication process.

Creating an Answer Sheet

 The first step in the Paperscorer process is for an educator to create answer ("bubble") sheets, based on a given assessment, for their students.  When this endpoint is called, Paperscorer dynamically generates the answer sheets based on the json data provided.  A unique URL is returned by the endpoints to a PDF file, which can be printed and distributed to students.  Students can fill these answer sheets out using pen or pencil.

Endpoints used  The following workflow describes this process.

Scanning Answer Sheets for Scoring

There are three ways that educators can send their scanned answer sheets to Paperscorer for scoring.  
  • Using the Paperscorer Mobile App - Responses are automatically sent to the Paperscorer services for scoring.  No integration effort required.
  • Scanning and Emailing - Responses are automatically sent to the Paperscorer services for scoring.  No integration effort required.
  • Scanning and Uploading - A means to upload scanned sheets must be added to your platform.
You will need to create a means up uploading PDF files to your platform so that the files can be sent to Paperscorer's web services.  Note that a single PDF file can contain answer sheets for multiple assessments and multiple students.  Once you receive a PDF file, it should be uploaded to submitAnswerSheetProcessingJob.  This endpoint creates a Job ID and begins processing the answer sheet using multiple threads/servers.  You can then periodically call the getProcessedFormIDs endpoint to determine which forms have been successfully processed in the job.

Endpoints Used The following workflow describes this process.

Retrieving Scores for Students

There are two approaches to retrieving student scores from Paperscorer: via callback method or via request.

​Push - Callback Method
If you would like for Paperscorer to push scores to your system as soon as the scores are captured, we recommend using the Callback method. Documentation on this can be found here.  Note that if you are using Learnosity with the Callback method, submitting scores to Learnosity and retrieving session information must be done from your system.

Pull Approach
To return detailed results for each student related to a processed form, call the getScoresbyFormID endpoint.  This endpoint returns detailed results for each student answer sheet successfully processed by Paperscorer.  After receiving student responses and syncing the responses with your platform, it is important for your to call the acknowledgeSyncScore endpoint. This endpoint removes the student's results from subsequent responses.

Endpoints Used ​The following workflow describes this process.

Error Resolution

While Paperscorer makes every attempt to read and score answer sheets, there are times when an answer sheet cannot be successfully scored by our technology.  This occurs in the following cases:
  • If an answer sheet was scanned in very low-light or from a low quality printing.
  • If a scanned answer sheet does not contain the outside borders or codes at the bottom of the answer sheet.
  • If a student has marked more than one answer for a numeric, matching or sorting question.
For these scenarios we offer a tool that can be incorporated into your platform.  This tool is designed to render within an iFrame within your platform.  The iFrame will load any exceptions related to an educator's scans.  On the left side, the educator will see the scanned image of the answer sheet.  On the right, the teacher will see a web-form that allows them to overwrite and submit a student's score.
When your account set up, Paperscorer will provide you with a secure encryption key.  This key is to be used to encrypt data that is passed via a javascript function within your platform.  Paperscorer will also provide a javascript function that is to be used to generate the iFrame.  The process for launching the iFrame is as follows:
  1. Using the session information returned by userLogin and the secure encryption key given to you during setup, your platform should encrypt the variables required for the javascript function.
  2. Your platform should dynamically render the javascript function on the web page that will display the link or button that is to launch the iFrame.  This javascript function will contain the encrypted string as a parameter.
  3. Structure your page so the javascript function is invoked onclick of the link or button that is to launch the iFrame.
  4. Paperscorer will use the encryption key associated with your platform to decrypt the variables sent to the iFrame and launch the iFrame, presenting all outstanding errors associated with the educator's account.