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.
NOTE: To acutally execute plagiarism checks and retrieve results your account needs to be unlocked and equipped with test credit.
The reply is generally sent as JSON data, with the exception of RETRIEVE method with MODE larger or equal 3: Annotated docx files (RETRIEVE method with MODE=3) are sent as plain binary data. RETRIEVE method with MODE=4 or higher will return reports in valid HTML but not XML.
This document is intended as a reference or may give you a first idea of what is possible. Please do not hesitate to contact us at api@plagscan.com if you have questions!

API Documentation

Documentation

Status

There 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
Also see processing script example below!

When a document is submitted through the Submit method - the document's newly generated PlagScan ID (PID) is returned by this API call.
Then the document goes to a queue to be converted.
The document information is sent to the callback URL script when the upload/convertion is finished. If not set then is necessary to check for the document state afterwards.
If autocheck policy is off for the document owner the text will just be added to your set of texts. In this case you must call the Check method to initiate a plagiarism check. If is on then the plagiarism check will be started automatically after the upload. The document goes to a queue to be checked.
Have to wait until the check is completed. Another call will be sent to the callback URL script when the check is finished. If not set then is necessary to verify the document state afterwards.
Now you can call the Retrieve method to get the result of your check.

Callbacks / notifications

If 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:

The document is successfully uploaded/converted

    "docID": "8046327",
    "status": "0",
    "mode": "0",
    "words": "100"

the document status

The check/analysis is completed

8046327

In case the check process failed due to no PlagPoints available, the callback would return:

    "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

Only SSL calls to api.plagscan.com are accepted
Your 32 character API key and your client ID (from API administration area) are ONLY required to get an access token.
The access token that you get is ALWAYS required in every request (except for the access token request).

The access token is randomly generated
The access token has associated the organization ID, so please don't pass access token to other person for security reasons.
The access token has an expire time. After that time is useless for requests.
The expire time of the access token is showed in the returned value of the access token request. 3600 seconds as default.
The access token can be linked to a user of the organization for authentification purpose.
You can refresh your access token in case it is expired.

Access can be restricted to one or several IPs:

Leave setting blank or set to 255.255.255.255 for no restriction
Enter one IP if request always come from one server
IP range with wildcard: 1.2.3.*
IP range in CIDR format: 1.2.3/24 OR 1.2.3.4/255.255.255.0
Start-End IP range: 1.2.3.0-1.2.3.255

To receive (optional) callback notifications please adapt your firewall settings to accept incoming connections from PlagScan. Currently all notification communication is bundled and will come from IPs 195.201.8.187, 136.243.25.50, 144.76.58.15 and 148.251.180.22 (we will notify clients of any upcoming changes).

Admin/User usage & access token

When 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:

Admin: when an access token is requested and no user ID is provided.

In this case the access token won't be associated with a user. If the token obtained is used for any request to the API, it will be understood that the one making the request is the administrator of the organization.

User: when an access token is requested and a user ID is provided.

user

It is possible to provide both kind of tokens at the same time and used as well for request from different users without any inconvenience. Example use case:

Submit a document

With a token associated to a user (not admin): the document submitted will be own by the user with ID corresponding to the access token.
With a token not associated to a user (admin): the document submitted will be own by the organization admin if the parameter corresponding to the ID of the owner is not provided.

Delete a document from the repository

With token associated to a user (not admin): the user will be identify and is not the organization admin, so a error message will be returned
With token not associated to a user (admin): the request will return a sucessful result.

Access token request

Make a POST request to https://api.plagscan.com/v3/token
Provide two parameters:

client_id: your organization ID
client_secret: the API key

You will get a JSON response like this:

{
  "access_token": "ec24a6de1ba8c78eaea46dfyhv5955d4c78154ca",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": null
}

In case you want to associate the access token with a user, provide the ID of the user with the parameter user in the request.

Request Format

Each 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.

/users
/documents
/groups
/submissions
/repositories

So you can use RESTful URLs to access to those resources. For example:

GET /users - Returns the list of users
GET /users/612 - Returns the user with the ID 612
POST /users - Creates a new user

Required Parameters: API Credentials

Parameter	Value
access_token	The access token received.

Response Format

Results of a request are sent as JSON data - with the exception of Word 2007/2010 docx files, which are sent as plain data.
Plagiarism reports are not generated instantly. To let you know when results are available you can give the address of a call-back script in your API integration settings. This URL will be called once analysis is complete, e.g. http://yourdomain.com/notice.asp?12345 - where 12345 is the document's unique identifier (PID). See processing script example below.
Make sure your script runs in stay-alive mode: PlagScan terminates the connection after 5 seconds and does not wait for your script to finish execution.

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 Codes

There is a set of significant HTTP status codes:

200 OK - Response for a successful GET and PATCH.
201 Created - Response for a POST request that creates a resource. Also include a "location" field with the URL pointing to the new created resource.
204 No Content - Response to a succesful request with no information to return, like DELETE or PUT.

And there are two groups of error codes: 4xx codes for client errors and 5xx codes for server errors:

400 Bad Request - Malformed syntax in the request. Should modify the request.
401 Unauthorized - When the access token is not provided, it is not valid or it is expired.
404 Not Found - The resource or the URL that you are requesting doesn't exist.
500 Internal Server Error - Error from the server side.

Additional information

Duplicated Submissions

After 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.

Timeouts

It'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 formats

PlagScan API v3 supports the following types:

Preferred format	Formatting will be preserved
docx - Best result for the word report	Microsoft Word 2007/2010/2013/2016 [.docx]
pdf - Best result for the browser report	Portable Document Format (Adobe Acrobat) [.pdf]
Other possible formats	Conversion to .docx, some formatting might be lost
doc	Microsoft Word 97/2000/2003/XP [.doc]
txt	Plain Text [.txt]
html	HTML Document [.html]
pages	Pages for MAC (Apple iWork) [.pages]
ppt	Microsoft Powerpoint [.ppt]
doc6	Microsoft Word 6.0 [.doc]
doc95	Microsoft Word 95 [.doc]
wps	Microsoft Works [.wps]
wpd	WordPerfect [.wpd]
odt	Open Document Text (LibreOffice) [.odt]
ott	Open Document Text [.ott]
rtf	Rich Text Format [.rtf]
sdw	StarWriter 5.0 [.sdw]
sdw4	StarWriter 4.0 [.sdw]
sdw3	StarWriter 3.0 [.sdw]
sxw	OpenOffice.org 1.0 Text Document [.sxw]
Supported formats	Formatting will be lost
xlsx	Microsoft Excel [.xlsx]
xls	Microsoft Excel [.xls]
pptx	Microsoft Powerpoint [.pptx]
docbook	DocBook [.xml]
ooxml	Microsoft Office Open XML [.xml]
pdb	AportisDoc (Palm) [.pdb]
latex	LaTeX 2e [.ltx]
numbers	Numbers for MAC (Apple iWork) [.numbers]
key	Key for MAC (Apple iWork) [.key]

Zip files are not supported for submissions on API v3.

Remote shadow scripts for full reports CMS integration

Note: 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.
You can (and should) add your own browser-based login and access rights checking. See the included ReadMe file for details.
To get an impression of what this can look like have a look at the working example:
https://www.wahlkurse.de/PlagScanAPI/view?2150873
The example simply uses the test scripts, without login / access check.
All the links to other report types (docx, pdf, list) work fine within the local domain, wahlkurse.de in this test.
Only in the background the scripts fetch requested content via the API from PlagScan.
Hint: The Internal Link URL for the example is simply https://www.wahlkurse.de/PlagScanAPI
Download scripts for shadowing PlagScan

Sample code

PHP:
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

<< Homepage

API Documentation >>