Documentation API

    PlagScan API guide, version 2.2, 6th January 2017
    PlagScan API specification

    Plagiarism checker API integration


    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/

    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


    Sample code
    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!
    <<   Homepage
Close
Vous avez oublié votre mot de passe?
Tapez votre adresse E-mail


Nouveau mot de passe
Close
Choisissez votre utilisation
Notre cadeau de bienvenue: Recevez un crédit de 20 unités PlagScan (soit 2000 mots) et lancez aussitôt une analyse de texte.
Vous représentez une université, une école ou une entreprise - Ce compte comprend plusieurs sous-comptes-utilisateurs, votre portail PlagScan individualisé et bien d'autres fonctions adaptées aux organisations.
Close
Créer un compte gratuitement et immédiatement
Ouvrir un nouveau compte







Ou se connecter avec
En cliquant sur Inscription, vous acceptez nos Conditions d'utilisation.
Notre cadeau de bienvenue: Recevez un crédit de 20 unités PlagScan (soit 2000 mots) et lancez aussitôt une analyse de texte.
Close
Créer un compte gratuitement et immédiatement






En cliquant sur Inscription, vous acceptez nos Conditions d'utilisation.
Vous représentez une université, une école ou une entreprise - Ce compte comprend plusieurs sous-comptes-utilisateurs, votre portail PlagScan individualisé et bien d'autres fonctions adaptées aux organisations.