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