PlagScan API guide, version 2.2, 6th January 2017

Important note: This API will soon receive a major overhaul to version 3, see the Blog article http://blog.plagscan.com/hapi-new-year-a-better-integration-in-2017/

Update - Beta now available: PlagScan API Version 3 and API v3 Documentation

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.
Requests are always send as a POST request to https://api.plagscan.com/. They have to be accompanied by the organization's identification key. To get an API key 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 XML 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!
See sample code below.

PlagScan System Integrations

Remote shadow scripts for full reports CMS integration

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

API Workflow

  Submit → Check → Callback → Retrieve
You submit a document through the Submit method - the text's newly generated PlagScan ID (PID) is returned by this API call. If autocheck is off for the document owner the text will just be added to your set of texts. Otherwise you have to call the Check method to initiate a plagiarism check.
Afterwards you have to wait until the check is completed. Once analysis is completed, PlagScan will call your organization's callback script with the text's PID (or you can check back periodically what the state of your document is, method List).
Now you can call the Retrieve method to get the result of your check.

General format of a Request

 

Security requirements

• Only SSL calls to api.plagscan.com are accepted
• Your 32 character API key is always required
• Access can be restricted to one or several IPs:
1. Leave setting blank or set to 255.255.255.255 for no restriction
2. Enter one IP if request always come from one server
3. IP range with wildcard: 1.2.3.*
4. IP range in CIDR format: 1.2.3/24 OR 1.2.3.4/255.255.255.0
5. 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 IP 136.243.11.230 (in the future this will change to a range of IPs).

 

Request Format

Each POST request consists of required (and possibly optional) parameters and their values. Parameter names are not case sensitive. The examples in this document use UPPERCASE for parameter names and divide the parameters into required security parameters and body parameters. The former are always the same regardless of the function executed while the latter parameters depend on the method called.

Required Authentification Parameters	USER KEY VERSION
Body Parameters	METHOD +methodSpecificParameters

 

Required Parameters: API Credentials

Parameter	Value
USER	Your PlagScan Username.
KEY	Your PlagScan API Key.
VERSION	Version number of the API service, currently 2.1 .
METHOD	Command you want to execute

 

Return Format

Results of a request are sent as XML 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.

 

Supported methods

 

Method Submit – submit a document file (Analysis does not start automatically unless turned on in the user's settings. One single document per call; zip archives are not supported for API submissions. To ensure proper text conversion please use the common ending for the file type - i.e. .txt for a plain text file. If you do not need annotated MS Word versions of your text turn docx generation off in the user settings - this will speed up submission and analysis!)

Parameter	Value
METHOD	Submit
DATA	The file you want to analyse, including filename (HttpMultiPart; see examples!)

After analysis, notification is sent to the call-back address given in your institution’s administration settings.
(PID as querystring, see processing script example)

 

Method Submit – submit plain text (Analysis does not start automatically unless turned on in the user's settings. If you do not need annotated MS Word versions of your text turn docx generation off in the user settings - this will speed up submission and analysis!)

Parameter	Value
METHOD	Submit
FILENAME	Title/identifier of the text
TEXT	Text data

After analysis, notification is sent to the call-back address given in your institution’s administration settings.
(PID as querystring, see processing script example)

 

Method Retrieve – retrieve plagiarism report data for a document

Parameter	Value
METHOD	Retrieve, expects the following:
PID	PlagScan unique identifier for the text to retrieve
MODE	What shall be sent – Report with particular detail level or annotated docx file? See "Retrieve report modes" below for details.

 

Method List – list all documents stored for user

Parameter	Value
METHOD	List
START	Which document to start with (0 is the newest document)
NUM	How many documents from start shall be returned (set to 0 for document count)
MODE	Detail level of results sent, see below.

 

Method Check – analyze a document

Parameter	Value
METHOD	Check, requires the following:
PID	PlagScan unique identifier for the text to check

 

Method Delete – delete a document (and possibly the corresponding report)

Parameter	Value
METHOD	Delete, requires the following:
PID	PlagScan unique identifier for the text to delete

 

Method GetConfig – retrieve user configuration

Parameter	Value
METHOD	GetConfig

 

Method SetConfig – set user configuration property

Parameter	Value
METHOD	SetConfig
PROPERTY	Name of the property to be set, see below for permitted properties
VALUE	New value of the property, see below for permitted types

 

Administrative Functions

The methods listed below will only work when the username sent with the request belongs to the institution’s administrator for PlagScan. Otherwise an “N/A” error message is returned.

Note that the default configuration for new users and the institutional limit for the usage of additional credits as well as billing details etc. can currently not be changed via the API.

 

Method ListUser – list one or all users belonging to this account (one user in detail or all users with id and username only)

Parameter	Value
METHOD	ListUser
USERID	ID number of the user whose details are requested or -1 to list all users

 

Method AddUser – add a new user for this institution

Parameter	Value
METHOD	AddUser
USERNAME	Username for the new user (may equal e-mail address below)
EMAIL	The new user’s e-mail address
FIRSTNAME	[Optional] The new user’s given name
LASTNAME	[Optional] The new user’s family name
SENDMAIL	[Optional] Whether to send a welcome message with the generated password to the new user: (0) no message is sent - default or (1) send message

 

Method DelUser – delete a user from this institution

Parameter	Value
METHOD	DelUser
USERID	ID number of the user to be deleted

 

Method ConfigUser – change configuration for existing user

Parameter	Value
METHOD	ConfigUser
USERID	The user’s ID number
MODE	Set the user mode to “unlimited” (0) or “allocated” (1)
LIMIT	Set the user’s usage limit (if allocated mode is set) in PlagPoints

 

Parameter / value details

 

Retrieve report modes

·    0 Retrieve statistics only, such as plagiarism level, number of words, wait etc. (n.b.: wait is in ms, the report timestamp - creation timestamp, so a negative value indicates that the analysis has not started at all or finished yet.)

·    1 Retrieve document's plain text and report links; to list of possible plagiarism sources and in-document view of possible plagiarism sources; e.g. https://www.plagscan.com/view?6055

·    2 Retrieve XML with data on all possible plagiarism sources

·    3 Retrieve annotated Docx document (if available, depending on user configuration)

·    4 Retrieve HTML document with annotations

·    5 Retrieve HTML report of matches sorted by relevance

·    6 Retrieve new style (interactive) HTML document with annotations

·    7 Retrieve latest report type (with formatting and images) - returns URL (link gives temporary access for one hour)

·    8 PDF version of HTML document with annotations

·    9 PDF version of HTML report of matches sorted by relevance

 

List detail level

·    0 PlagScan document IDs, user unique IDs, number of words and submission datetime, plus analysis state (0 not carried out, 1 waiting, 2 ongoing, 3 finished, 4 queued)

·    1 In addition to the above: Plagiarism level, Filename and Label

·    2 In addition to the above: Content preview (first 85 characters)

 

Configuration properties and values

·    LANG Set language to 0 English, 1 German, or 2 Spanish

·    EMAIL Email notification: 0 never, 1 always, 2 only if “red” plagiarism level

·    DOCX Generate Docx documents: 0 generate and email, 1 generate only, 2 do not generate

·    AUTO Autostart plagiarism checks: 0 do not start analysis automatically, 1 start analysis automatically as soon as possible

·    SHARE Share my documents for analysis with and compare to: 0 no one (compare to web sources only if activated), 1 no one (compare to my documents and web sources if activated), 2 my institution (compare to institution database and web sources if activated), 3 general database (compare with general database and web sources if activated)

·    WEB Check against the Internet for plagiarism : 0 off (do not compare to web sources), 1 on (compare to web sources)

·    YLW Set from which percentage of matched text the yellow PlagLevel starts: 10 is the default, meaning over one percent of text matching, can take any integer value up to 1000 (for 100%)

·    RED Set from which percentage of matched text the red PlagLevel starts: 50 is the default, meaning over five percent of text matching, can take any integer value up to 1000 (for 100%)

·    SSTY Set sensitivity of the analysis to: 0 low (only report longer matches) 1 medium (balanced approach, recommended)   2 high: report many, even short matches

·    DEL Automatically remove data after: 0 after one week, 1 after four weeks, 2 after six months, 3 never delete automatically

Java:
Download Java sample code
PHP:
Download PHP sample code
.NET:
Download .NET sample code
Call-back script example:
Download PHP processing test call-back script
Scripts to use with your Internal Link URL:
Download scripts for shadowing PlagScan, i.e. let users navigate PlagScan reports in your Learning Management System's Domain and access rights management.
HTML testing forms:
testList
testSubmit (document file)
testSubmit (plain text)
testRetrieve
testCheck
testDelete
testGetConfig
testSetConfig
testListUser
testAddUser
testDelUser
testConfigUser
Test user data:
Username: apitest Key: W9fUaSq2vjkXUPMmenlmp3Xqnc1xWPtN
Note: NO changes are actually executed when using the test user data!