Optional Request Headers

You can add optional headers to the Http request. The headers are relevant for both the Academic and Businesses APIs and can be used with the following requests:

In this document:


Sandbox mode

You can test the integration with Copyleaks API for free using the sandbox mode. You will be able to submit content to scan and get back mock results, simulating the way Copyleaks will work.

To turn the sandbox mode on, add the http-header copyleaks-sandbox-mode to your calls. No matter what the value is.

Usage Example

Http Request headers:
  copyleaks-sandbox-mode

Http Callbacks

Copyleaks API supports callbacks that are invoked once there are updates with the scan process.

Tracking your processes is available by adding the token process ID {PID} as a parameter to your URL.

Usage Example

example.com/{PID} -> this will automatically lead to a url such as example.com/1074ae9d-ec1c-46ff-adc2-c294abed29f3. This will allow you to follow each process individually.

If the callback endpoint is unavailable, we will try again after 5 seconds for 3 times. If it is still unavailable, you will not be notified again.

In progress callbacks

You can receive the scan results as they are individually found, while the scan is still running.

To do so, add the header copyleaks-in-progress-new-result to your request and your endpoint as the value.

Usage Example

To get the results in real time to the URL: "http://yourendpoint.com" add the following header to your request:

Http Request headers:
  copyleaks-in-progress-new-result, "http://yourendpoint.com"

When a result is found, HTTP POST request will be sent to the callback endpoint. Once successfuly notified, you will recieve the following information to your endpoint:

  1. Result - a scan result.
Response Sample:
{
	    "URL":"http://example.com/ ",
	    "Percents":12,
	    "NumberOfCopiedWords":133,
	    "ComparisonReport":"https://api.copyleaks.com/v1/downloads/comparison?rid=1493025 ",
	    "CachedVersion":"https://api.copyleaks.com/v1/downloads/result-text?rid=1493025 ",
	    "Title":"Example Domain",
	    "Introduction":"No introduction available.",
	    "ComperisonEmbed":"https://copyleaks.com/compare/d69167b7-670b-491f-827f-46ba5ffd43a0/1493025 "
}

Completion-Callbacks

When using callbacks, there is no need to check the request's status manually. We will automatically inform you when the process has completed running and the results are ready. Add the Http request header copyleaks-http-completion-callback with the URL of your endpoint.

Usage Example

If you want a callback to your site and you want to add PID as a parameter you would add:

Http Request headers:
  copyleaks-http-completion-callback, http://mywebsite.com/callback/{PID}

When the API request status is completed, HTTP POST request will be sent to the callback endpoint. Once successfuly notified, you will recieve the following information to your endpoint:

  1. Status - if the status is 'finished' your results are ready to be viewed (if results were found), otherwise something has gone wrong with your scan.
  2. Results - an array with the scan results.
Response Sample:
{
   "status":"Finished",
   "total-results":1,
   "results":[
      {
         "URL":"http://example.com/",
         "Percents":14,
         "NumberOfCopiedWords":15,
         "ComparisonReport":"https://api.copyleaks.com/v1/downloads/comparison?rid=1493025",
         "CachedVersion":"https://api.copyleaks.com/v1/downloads/result-text?rid=1493025",
         "Title":"Title of the file",
         "Introduction":"This is how the text starts.",
         "EmbededComparison":"https://copyleaks.com/compare/d69167b7-670b-491f-827f-46ba5ffd43a0/1493025"
      }
   ]
}
In the rare case, that the amount of results exceeded the maximum permissible length, the amount of total-results will not match to the amount of results received to your endpoint. In this case, we will send to the endpoint the results with the highest precentage of copied content. You can call the result method (Academic \ Businesses \ Websites) to get all the results if needed.


Email-Callbacks

Register a callback email to get informed when the request has been completed.

When the API request status is complete, you will get an email to your inbox and the scan results will be available, using the result (Academic \ Businesses \ Websites) method.

Usage Example

Specify the copyleaks-email-callback request header with your email-address:

Http Request headers:
  copyleaks-email-callback, [email protected]

Custom Fields

You can add custom payload to the request headers. The payload is stored in a 'dictionary' representing a collection of string key and string value pairs.

Usage Example

To create a new payload with the key Message and the value 'Hello world!', add the following header to your request:

Http Request headers:
  copyleaks-client-custom-Message, Hello world!

To retrieve your custom fields use the function list (Academic \ Businesses \ Websites).

The custom fields limitations are:


Allow Partial Scan

If you don't have enough credits to scan the entire submitted text, part of the text will be scanned, according to the amount of credits you have left.

For example, you have 5 credits and you would like to scan text that requires 10 credits. If you added the copyleaks-allow-partial-scanto your request only 5 pages out of 10 will be scanned. Otherwise, none of the pages will be scanned and you will get back an error messsage stating that you don't have enough credits to complete the scan.


Compare Documents For Similarity

If you would like to only compare files and documents to one another and not against other online or external sources use the copyleaks-compare-documents-for-similarity header. This header can be used only with the following requests: