Paperscorer

  • Home
  • LMS Add-Ons
    • Canvas Add-on
    • Blackboard Add-on
    • Google Add-on
    • Learnosity Add-on
  • Pricing
  • For Developers
  • Help
  • Login
  • Home
  • LMS Add-Ons
    • Canvas Add-on
    • Blackboard Add-on
    • Google Add-on
    • Learnosity Add-on
  • Pricing
  • For Developers
  • Help
  • Login

Paperscorer Core Web Services

Paperscorer is technology that generates print answer and question sheets and automatically captures scores entered by users via mobile devices or standard scanners. Captured scores can then be sent back to external systems. These web services outline how to integrate Paperscorer technology with external systems.

RestService - oAuthoToken

An oAuth token is necessary for all endpoints within the Paperscorer API, so generating this should be the first step in your process.
Field
Type
Description
client_id
String
The client_id associated with your company as a Paperscorer API client.  This value will be given to you when your account is set up.
client_secret
String
The client_secret associated with your company as a Paperscorer API client.  This value will be given to you when your account is set up.
grant_type
String
Should be "client_credentials" to generate an oAuth token.
Success Response Example

    
Error Response

    

RestService - userLogin

Most of the web services within the Paperscorer API are done on behalf or a user within your system.  userLogin allows you to create a session within Paperscorer for one of your users.  If the user does not yet exist within Paperscorer, a new user will be created.

Request Metadata

Field
Type
Description
domain_name
String
The domain name associated with your company as a Paperscorer API client.  This value will be given to you when your account is set up.
first_name
String
The first name of the user for whom you are creating a Paperscorer session.
last_name
String
The  last name of the user for whom you are creating a Paperscorer session.
email
String
 A valid email of the user for whom you are creating a Paperscorer session.  Note that Paperscorer will send emails to users in certain cases.
is_active
integer
Indicates whether the user is active within your system or not.  1 for true; 0 for false.
is_student
integer
Indicates whether the user is a student.  1 for true; 0 for false.
deviceId
alphanumeric
Device ID of the user.  This is generally left blank unless being called form a mobile app.
client_id
​string
A client indicates the system that Paperscorer is integrated with.  In some cases, Paperscorer may provide you with your own client_id.  
platform
string
Platform from which the user is logging in.  Options are web, mobile or email.
Post Request Example

    

Response Metadata

Field
Type
Description
ResponseCode
integer
Indicates whether the user was logged in successfully.  1 for success; 0 for failure.
Access Token
​string
An access token generated to make calls on behalf of this uer.
Refresh Token
string
Initially blank.  This is kept for future purpose to refresh the oAuth token.
​message
string
The message indicating success or failure.
institution_id
integer
A unique ID assigned to your organization as a Paperscorer API user. This value should be saved as it is a required input for many other endpoints.
platforms
array
The platforms from which a user has logged in.
Scope
string
A string indicating the scope of permissions of this user.
user_id
integer
A unique identifier assigned to the user.  This value should be saved as it is a required input for many other endpoints.
is_new_user
​string
True if the user was created as part of this response; false if the user already existed.
is_skipped
​string
Token Type
string
The type of token awarded to the user.  This is typically "bearer."
user_license_type
string
This relates to trial or "premium" users.  Most users are PREMIUM where the Paperscorer API is being used.
paymentStatus
string
This relates to the nature in which a user pays for their subscription.  Most users are "manual: where the Paperscorer API​ is being used.
showExpiryAlert
integer
This is used in cases where a user's Paperscorer license has expired.  For most Paperscorer API users, this should return -1.
Expiry
integer
A value indicating the time remaining on a user's Paperscorer subscription.
Success Response Example

    
Error Response Example

    

RestService - saveTask

saveTask is used to generate a dynamic PDF Answer Sheet.  Answer sheets can contain as many as 200 questions of a variety of different question types, including multiple-choice, multiple-select, true/false, rubric, numeric, matching, sorting and essay.  

Request Metadata

Field
Type
Description
email
string
The email associated with the user on behalf of whom the answer sheets are being generated.  This is typically an educator who is using your system to grade a student.
institution_id
integer
The institution_id associated with your organization as a Paperscorer API user.  This is returned when you call userLogin.
domain_name
string
The domain name associated with your organization as a Paperscorer API user.  This will be provided to you by Paperscorer when your account is set up.
client_type
string
The type of system associated with your Paperscorer account.  This will be provided to you by Paperscorer when your account is set up.
status
string
A string indicating if the answer sheet is ready to be scanned and processed by Paperscorer.
threadCall
string
If true, the sheet generation will be processed in a separate thread.
json
json
Contains metadata for the various questions and possible answers that should appear in the answer sheet (see examples below)
json/question_text_available
integer`
0 or 1. If 1, then 'text' field in question array will be used for sequencing
json/scorerGrader
integer​
Kept for future purposes
json/assessment_name
string
The name of the assessment.  This name will appear at the top of the answer sheet.
json/ltst
string
A description of the assessment.
json/templateId
integer
Unique template to use in generating the answer sheet.  This can be customized. 1 should be used if the answer sheet should contain a student ID area where students can bubble in their student ID.  0 should be used when a distinct answer sheet should be generated for each student, where the student ID is encoded within the bar and QR codes of the answer sheet.
json/assessment_id
string
The unique identifier of the assessment within your system.  This ID should be linked to the form_id generated by Paperscorer in order to link unique assessment ID and the answer sheet generated by Paperscorer.
json/max_score
integer
The maximum score one can receive on an assessment.
json/students
array
An array containing the unique name, email and identifier of each student for whom an answer sheet should be generated.
json/questions
array
An array containing the question metadata.  See specific examples below.
json/questions/text
integer
Sequencing for questions, e.g., 1, 2, 3.
json/questions/type
integer
For use in multiple choice questions.  1 for single answer, 2 for multi-answer.
json/questions/qid
string
Unique question ID for the question in your system.
json/questions/essayPageArea
string
For use in determining the percentage of a page that should be used for an essay response area.  Supported values are "12.5," "25," "50," "75," or "100."
json/questions/essayLineHeight
string
For use in determining if lines should be displayed within an essay space on the answer sheet.  Supported values are "NONE," "STANDARD" for 20 pt, and "EXTRA SPACE" for 30pt.
json/questions/​numeric_option_values
array
For use in numeric questions.  A bubble will appear vertically for every value in the array.  Supported values are "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", ".", "-", "+", "/".
json/questions/
Post Request Example

    

Response Metadata

Field
Type
Description
ResponseCode
integer
Indicates whether the user was logged in successfully.  1 for success; 0 for failure.
Access Token
​string
An access token generated to make calls on behalf of this uer.
Refresh Token
string
Initially blank.  This is kept for future purpose to refresh the oAuth token.
​message
string
The message indicating success or failure.
institution_id
integer
A unique ID assigned to your organization as a Paperscorer API user. This value should be saved as it is a required input for many other endpoints.
platforms
array
The platforms from which a user has logged in.
Scope
string
A string indicating the scope of permissions of this user.
user_id
integer
A unique identifier assigned to the user.  This value should be saved as it is a required input for many other endpoints.
is_new_user
​string
True if the user was created as part of this response; false if the user already existed.
is_skipped
​string
Token Type
string
The type of token awarded to the user.  This is typically "bearer."
user_license_type
string
This relates to trial or "premium" users.  Most users are PREMIUM where the Paperscorer API is being used.
paymentStatus
string
This relates to the nature in which a user pays for their subscription.  Most users are "manual: where the Paperscorer API​ is being used.
showExpiryAlert
integer
This is used in cases where a user's Paperscorer license has expired.  For most Paperscorer API users, this should return -1.
Expiry
integer
A value indicating the time remaining on a user's Paperscorer subscription.
Success Response Example

    
Error Response Example

    
Support  |  Contact  |  Help  |  Terms of Use  |  Privacy Policy
​
.