Core API Documentation
The PaperScorer Core API enables institutions to include advanced printing and scanning capabilities into their platforms.
Authentication
Regardless of the PaperScorer process, the first step is to provide authentication as an API partner (oAuthToken) 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 the answer sheet creation 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.
- Submit Answer Sheet Processing Job (/rest/ps/submitAnswerSheetProcessingJob)
- Get Processed Form IDs (/rest/ps/getProcessedFormIds)
The following workflow describes the answer sheet scoring process.
Retrieving Scores for Students
There are two approaches to retrieving student scores from PaperScorer: via callback method or via request.
Push Approach
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
- Get Scores by Form ID (/rest/googleApi/getScoresByFormId)
- Acknowledge Sync Score (/rest/googleApi/acknowledgeSyncScore)
The following workflow describes the retrieving scores for students 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:
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.
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.
Structure your page so the javascript function is invoked onclick of the link or button that is to launch the iFrame.
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.
Decrypting Engine Responses
All responses from the PaperScorer engine are encrypted with a key. We share that key with our development partners so they can decrypt the response in realtime. Our system will attempt to send over the encrypted payload multiple times until we get a successful response from your server.
The decryption key is provided by PaperScorer when setting up the callback functionality. If you don't have a decryption key yet, please reach out to the PaperScorer support team.
We have created a few sample libraries to use with your application to assist in the decryption of our engine responses. We are always looking to create more samples in different languages. If you create one in a language we don't have, drop us a note so we can share it with the rest of the community.
Ready to start using the PaperScorer App?
You can create a free account with no obligation to purchase. Give our app a try and see if you like it. You can scan up to 100 testing sheets completely free.
