Man touching touch screen that shows hexagons with software icons and API text

PlagScan API specification

Do you want to build an application that uses PlagScan as a service? Or do you want to integrate plagiarism checking into a third-party content management system, like Sharepoint, Blackboard or 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 increased functionality and more security.

GET, POST, PATCH, PUT or DELETE requests are send to https://api.plagscan.com/v3/. They must always be accompanied by the access token. To get an access token you first need an API key, and for that you'll have to register for a PlagScan Pro organizational account. After logging in as an administrator, click on the 'API Integration' link on the menu. Now you can generate your PlagScan API key, set the call-back URL for completion notifications, and define the IP address/range (CIDR format: 1.2.3.4/24) from which requests with your API key may originate.
NOTE: In order to actually execute plagiarism checks and retrieve results, your account needs to be unlocked and must have some test credit available.
The reply is generally sent as JSON data, with the exception of a RETRIEVE method with a MODE  equal to or greater than 3: Annotated docx files (RETRIEVE method with MODE=3) are sent as plain binary data. A RETRIEVE method with MODE=4 or higher will return reports in valid HTML but not XML.
This document is intended as a reference to give you a basic idea of what is possible. Please do not hesitate to contact us at api@plagscan.com if you have questions!

 

API Documentation v3

Documentation

 

Status

There is an API endpoint that can be used to check the API server status.

It should return an HTTP code 200.

https://api.plagscan.com/v3/ping

 

API Workflow

  Submit  Check  Callback  Retrieve
Documents are submitted using the Submit method, and 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 use the Check method to initiate a plagiarism check, and then wait until the check is done. Once completed, PlagScan will call your organization's callback script with the text's PID. (If you wish to view the status of your document while the plagiarism scan is still in progress, you can also use the List method.)
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 and your client ID are ONLY required to get an access token.
  • The access token that you get is ALWAYS required for every request (except for the access token request).
    1. The access token is randomly generated
    2. The access token includes the associated organizational ID, so for security reasons, please don't share it with other parties.
    3. The access token has an expiration time after which it is no good for further requests.
    4. The expiration time of the access token is shown in the returned value of the access token request, using 3600 seconds as a default.
    5. You can refresh your access token when it expires.
  • Access can be restricted to one or more IPs:
    1. Leave setting blank, or set it 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).

 

Access token request

  • Make a POST request to https://api.plagscan.com/v3/token
  • Provide two parameters:
    1. client_id: your organizational ID
    2. client_secret: the API key
  • You will get a JSON response like this:

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

Request Format

Each GET, POST, PUT, PATCH or DELETE request consists of required - and sometimes also optional - parameters and their values. The former are always the same regardless of the function executed, while the parameters depend on the method called. Since it is a REST API we have defined a number of resources:

  • /users
  • /documents
  • /groups
  • /submissions
  • /repositories

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

The response to a request is 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.

 

Sample response 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" 
  } 
}

 

If something goes wrong, the request will return an error response such as this:

{ 
  "error" : 
  { 
     "code" : 422, 
     "message" : "Validation failed for the field id" 
  } 
}

 

Response Codes

One group of response codes consists of HTTP status codes:

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

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

  • 400 Bad Request - Malformed syntax in the request. Request should be modified.
  • 401 Unauthorized - When the access token is not provided, invalid or 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.

 

 

 

Sample code

PHP:
Download PHP sample code

Java:
Download Java sample code

HTML testing forms:
testGetAccessToken
testListUser
testAddUser
testSubmit (document file)
testCheck
testRetrieve
Test user data:
Access Token: ca31ca2e74c84512a8554a069b0f985068804b05
Note: NO changes are actually executed when using the test user data, even though realistic-looking sample messages are displayed!