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: 220.127.116.11/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 firstname.lastname@example.org if you have questions!
API Documentation v3
There is an endpoint of the API that could be used to check the API server status.
It should return HTTP code 200.
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
- 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).
- The access token is randomly generated
- The access token has associated the organization ID, so please don't pass access token to other person for security reasons.
- The access token as an expire time. After that time is useless for requests.
- The expire time of the access token is showed in the returned value of the access token request. 3600 seconds as default.
- You can refresh your access token in case it is expired.
- Access can be restricted to one or several IPs:
- Leave setting blank or set to 255.255.255.255 for no restriction
- Enter one IP if request always come from one server
- IP range with wildcard: 1.2.3.*
- IP range in CIDR format: 1.2.3/24 OR 18.104.22.168/255.255.255.0
- Start-End IP range: 22.214.171.124-126.96.36.199
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 188.8.131.52 (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:
- client_id: your organization ID
- client_secret: the API key
- You will get a JSON response like this:
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.
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
The access token received.
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:
"lastname": "Prieto Lopez",
Could happen that the request goes wrong and return an error response. For example like this:
"code" : 422,
"message" : "Validation failed for the field id"
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.
HTML testing forms:
testSubmit (document file)
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).