PlagScan API guide, version 2.02, 03 August 2011
Momentan leider nur auf Englisch verfügbar!

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://www.plagscan.com/api/. 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 go to the settings menu and change the user interface to 'extended'. Afterwards your adminstration menu will display 'API Integration'. Here 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.
The reply is generally sent as XML data, with the exception of RETRIEVE method with MODE=3, MODE=4, MODE=5: Annotated docx files (RETRIEVE method with MODE=3) are sent as plain binary data. RETRIEVE method with MODE=4 or 5 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.

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 https://www.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

 

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, such as 2.0 .
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 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	The new user’s given name
LASTNAME	The new user’s family name

 

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 hits and sources

·    1             Retrieve links; to list of possible plagiarism sources; e.g. http://www.plagscan.com/report?6055

and in-document view of possible plagiarism sources; e.g. http://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

 

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 (compare to): 0 no one (compare to web sources only), 1 no one (compare to web and my documents), 2 my institution (compare to institution database), 3 general database (compare with general database)

·    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
Processing script example:
Download PHP processing test call-back script
HTML 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!