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? 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 v3

Documentation

 

Status

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

 It should return HTTP code 200.

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

 

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 and your client ID 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).
    1. The access token is randomly generated
    2. The access token has associated the organization ID, so please don't pass access token to other person for security reasons.
    3. The access token as an expire time. After that time is useless for requests.
    4. The expire time of the access token is showed in the returned value of the access token request. 3600 seconds as default.
    5. You can refresh your access token in case it is expired.
  • 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).

 

Access token request

  • Make a POST request to https://api.plagscan.com/v3/token
  • Provide two parameters:
    1. client_id: your organization 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 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.

 

 

 

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! ; Also some testing forms as 'Submit' doesn't allow to use it, but shows a real message example (with a previous uploaded file).