PlagScan API guide, version 3.1, 16th September 2020
PlagScan API specification Plagiarism checker API integration
Do you want to build an application that uses PlagScan as a service? Want to integrate plagiarism checking into your third party content management system like Sharepoint, Blackboard, Moodle? This might well be the missing puzzle piece. The API provided by PlagScan provides easy access to administrative as well as user tasks. PlagScan bring you a new version of the API based on RESTful architecture, with new functionalities and more security. GET, POST, PATCH, PUT or DELETE requests are send to https://api.plagscan.com/v3/. They have to be always accompanied by the access token.
To get an access token you first need an API key, for this you will have to register for a PlagScan Pro organization account. After logging in as administrator click on the 'API Integration' link in the menu. Now you can generate your PlagScan API key, set the call-back URL for completion notifications as well as define the IP address or IP range (CIDR format: 1.2.3.4/24) from which requests with your API key may originate. API DocumentationDocumentationStatusThere is an endpoint of the API that could be used to check the API server status. It should returns HTTP code 200. https://api.plagscan.com/v3/ping API Workflow
Submit → Convert → Callback → Check → Callback → Retrieve
Callbacks / notificationsIf you have set up a Callback URL in the API configuration, PlagScan will call your organization's callback script with the documents's information, so is not necessary to check back periodically what the state of your document is.There are 2 callbacks, and each of them send the following information about the document:
"docID": "8046327",
"status": "0",
"mode": "0",
"words": "100"
In case of a plaintext extraction error, mode would be 254 and words 0, e.g. the request would look like this: docID=126172679&status=0&mode=254&words=0
8046327
"docID": "8046327",
"usrID": "19",
"mode": "0",
"error": "NOCRED"
As we use a queue for the uploading process, during this it is not possible to retrieve the information of the document (such as plaintext, number of words, ...) or run the analysis. Only after the process is completed and received the callback, the document information will be available. General format of a Request
Security requirements
Admin/User usage & access tokenWhen you are going to get an access token to use the API two options are given: associate the token with a user or not. Depending on the option you can have a different mode of use of the API requests:
Access token request
{
"access_token": "ec24a6de1ba8c78eaea46dfyhv5955d4c78154ca",
"expires_in": 3600,
"token_type": "Bearer",
"scope": null
}
Request FormatEach GET, POST, PUT, PATCH or DELETE request consists of required (and possibly optional) parameters and their values. The former are always the same regardless of the function executed while the latter parameters depend on the method called. Since it is a REST API we have a number of resources defined. Required Parameters: API Credentials
Response FormatResults of a request are sent as JSON data - with the exception of Word 2007/2010 docx files, which are sent as plain data.
Response example requesting the information of one user:
{
"data": {
"internalID": "1594694",
"deptID": "-1",
"title": "",
"username": "Jprieto@plagscan.com",
"firstname": "Jesus",
"lastname": "Prieto Lopez",
"language": "0",
"email": "jprieto@plagscan.com",
"credits": "1",
"institutionMode": "0",
"creditLimit": "0",
"yellowLevel": "10",
"redLevel": "50",
"checkPolicy": "47",
"emailPolicy": "3",
"autoPolicy": "0",
"docxPolicy": "1",
"citePolicy": "1",
"biblioPolicy": "0",
"detailPolicy": "1"
}
}
Could happen that the request goes wrong and return an error response. For example like this:
{
"error" :
{
"code" : 422,
"message" : "Validation failed for the field id"
}
}
Response CodesThere is a set of significant HTTP status codes:
Additional information
Duplicated SubmissionsAfter monitoring the document submission functionality a behavior of some implementations of our users was discovered. In some cases the same file was uploaded repeatedly in a short period of time (1-5 seconds). In order to ensuring the smooth running of our document submission functionality efficiently, we have develop a solution trying to avoid the overload of our system.The submit requests containing the same document will be treated like duplicated submissions if is performed in less than 5 seconds from the previous one. In these cases the ID of the previous document will be returned.
TimeoutsIt's not often that happens but we are aware that there may be high peaks of use of our API and the responses may take a little longer than usual. To avoid timeouts in requests it is recommended to set a timeout time of 3 seconds in your implementation.
Supported file formatsPlagScan API v3 supports the following types:
Remote shadow scripts for full reports CMS integrationNote: This is for old report view. We recommend to use the new report to avoid using shadow scripts. More information about Retrieve report here.
These scripts allow your users to fully navigate PlagScan reports within your Content / Learning Management System. Sample codePHP: Download PHP sample code Java: Download Java sample code (various snippets and classes) Download Java workflow code (all the way from file upload to check result, updated 2019-08-19) HTML testing forms: testGetAccessToken testListUser testAddUser testSubmit (document file) testSubmit (plaintext) testCheck testRetrieve |