Exclude Template Text

The Exclude Template feature allows you to refine the analysis of documents by excluding specific sections based on a predefined template. This is particularly useful for scenarios like checking student exams where the questions are the same for everyone, and you only want to scan the student’s answers. This guide will walk you through the process of creating a template and then using it to exclude content from your scans.

How it works

To better understand how template exclusion works, consider the following scenario where a teacher wants to scan student exams but exclude the questions.

The Template (indexed beforehand)	Student Submission (the file you scan)	What Copyleaks Scans (the actual analysis)
Question 1: Explain the process of photosynthesis.	Question 1: Explain the process of photosynthesis. Answer: Photosynthesis is the process used by plants…	~~Question 1: Explain the process of photosynthesis.~~ Answer: Photosynthesis is the process used by plants…

By excluding the template text, the plagiarism scan focuses solely on the student’s original answer, preventing false positives from the question text itself.

Template sourcing

Templates for exclusion can be referenced in two ways:

From a normal submitted scan: Reference any existing scanId from your submissions (saved short-term which is determined by the expiration property).
From your Private Cloud Hub: Index the template document into your Private Cloud Hub (for recurring or long-term use).

This approach is widely used by many institutions to ensure that commonly repeated content, such as exam questions, rubrics, or boilerplate instructions, does not affect results.

Get started

Before you begin

Before you start, ensure you have the following:

An active Copyleaks account. If you don’t have one, sign up for free.
You can find your API key on the API Dashboard.

Installation

Choose your preferred method for making API calls.

# macOS
brew install curl

# Ubuntu/Debian
sudo apt-get install curl

# Windows - download from https://curl.se

pip install copyleaks

npm install plagiarism-checker

Install-Package Copyleaks

composer require copyleaks/php-plagiarism-checker

gem install plagiarism-checker

<!-- Add to your pom.xml (requires Java 11+) -->
<dependency>
    <groupId>com.copyleaks.sdk</groupId>
    <artifactId>copyleaks-java-sdk</artifactId>
    <version>5.1.0</version>
</dependency>

HTTP needs no installation - call the API with any standard HTTP client, or import our Postman collection for a quicker start.

To perform a scan, we first need to generate an access token. For that, we will use the login endpoint. The API key can be found on the Copyleaks API Dashboard.Upon successful authentication, you will receive a token that must be attached to subsequent API calls via the Authorization: Bearer <TOKEN> header. This token remains valid for 48 hours.

POST https://id.copyleaks.com/v3/account/login/api

Headers
Content-Type: application/json

Body
{
    "email": "[email protected]",
    "key": "00000000-0000-0000-0000-000000000000"
}

export COPYLEAKS_EMAIL="[email protected]"
export COPYLEAKS_API_KEY="your-api-key-here"

curl --request POST \
  --url https://id.copyleaks.com/v3/account/login/api \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data "{
    \"email\": \"${COPYLEAKS_EMAIL}\",
    \"key\": \"${COPYLEAKS_API_KEY}\"
  }"

from copyleaks.copyleaks import Copyleaks

EMAIL_ADDRESS = "[email protected]"
API_KEY = "your-api-key-here"

# Login to Copyleaks
auth_token = Copyleaks.login(EMAIL_ADDRESS, API_KEY)
print("Logged successfully!\nToken:", auth_token)

const { Copyleaks } = require("plagiarism-checker");

const EMAIL_ADDRESS = "[email protected]";
const API_KEY = "your-api-key-here";
const copyleaks = new Copyleaks();

// Login function
function loginToCopyleaks() {
  return copyleaks.loginAsync(EMAIL_ADDRESS, API_KEY).then(
    (loginResult) => {
      console.log("Login successful!");
      console.log("Access Token:", loginResult.access_token);
      return loginResult;
    },
    (err) => {
      console.error('Login failed:', err);
      throw err;
    }
  );
}

loginToCopyleaks();

import classes.Copyleaks;
import models.response.CopyleaksAuthToken;

String EMAIL_ADDRESS = "[email protected]";
String API_KEY = "00000000-0000-0000-0000-000000000000";

// Login to Copyleaks
try {
    CopyleaksAuthToken authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
    System.out.println("Logged in successfully!");
} catch (Exception e) {
    System.out.println("Failed to login: " + e.getMessage());
    System.exit(1);
}

Response

{
    "access_token": "<ACCESS_TOKEN>",
    ".issued": "2025-07-31T10:19:40.0690015Z",
    ".expires": "2025-08-02T10:19:40.0690016Z"
}

Save this token. It is valid for 48 hours and can be reused for subsequent API calls.

Create a template (index a document)

First, you need to submit the document that contains the text you want to exclude (the template). You will “index” this document into a repository (either in your Private Cloud Hub or Shared Data Hub).In this example, we will submit a file with the ID my-template-index to a repository named my_private_cloud_exam_template.

PUT https://api.copyleaks.com/v3/scans/submit/file/my-template-index
Content-Type: application/json
Authorization: Bearer <YOUR_AUTH_TOKEN>

{
  "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
  "filename": "exam_template.txt",
  "properties": {
    "action": 2,
    "indexing": {
        "repositories": [
            {
                "id": "6e870e0bb2264",
                "includeMySubmissions": true,
                "includeOthersSubmissions": true
            }
        ],
        "copyleaksDb": false
    },
    "webhooks": {
        "status": "https://your-server.com/webhook/{STATUS}"
    }
  }
}

curl -X PUT "https://api.copyleaks.com/v3/scans/submit/file/my-template-index" \
     -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
           "filename": "exam_template.txt",
           "properties": {
             "action": 2,
             "indexing": {
               "repositories": [
                 {
                   "id": "6e870e0bb2264",
                   "includeMySubmissions": true,
                   "includeOthersSubmissions": true
                 }
               ],
               "copyleaksDb": false
             },
             "webhooks": {
               "status": "https://your-server.com/webhook/{STATUS}"
             },
             "sandbox": true
           }
         }'

import requests
import base64

# Template content
template_content = "This is the exam template text."
base64_content = base64.b64encode(template_content.encode()).decode('utf-8')

url = "https://api.copyleaks.com/v3/scans/submit/file/my-template-index"
payload = {
    "base64": base64_content,
    "filename": "exam_template.txt",
    "properties": {
        "action": 2,
        "indexing": {
            "repositories": [
                {
                    "id": "6e870e0bb2264",
                    "includeMySubmissions": True,
                    "includeOthersSubmissions": True
                }
            ],
            "copyleaksDb": False
        },
        "webhooks": {
            "status": "https://your-server.com/webhook/{STATUS}"
        },
        "sandbox": True
    }
}
headers = {
    "Authorization": "Bearer <YOUR_AUTH_TOKEN>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

const url = 'https://api.copyleaks.com/v3/scans/submit/file/my-template-index';
const headers = {
    'Authorization': 'Bearer <YOUR_AUTH_TOKEN>',
    'Content-Type': 'application/json'
};

const data = {
    base64: "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
    filename: "exam_template.txt",
    properties: {
        action: 2,
        indexing: {
            repositories: [
                {
                    id: "6e870e0bb2264",
                    includeMySubmissions: true,
                    includeOthersSubmissions: true
                }
            ],
            copyleaksDb: false
        },
        webhooks: {
            status: "https://your-server.com/webhook/{STATUS}"
        },
        sandbox: true
    }
};

axios.put(url, data, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

import classes.Copyleaks;
import models.submissions.CopyleaksFileSubmissionModel;
import models.submissions.properties.*;
import java.util.Base64;
import java.nio.charset.StandardCharsets;

String scanId = "my-template-index";
String base64Content = Base64.getEncoder().encodeToString("This is the exam template text.".getBytes(StandardCharsets.UTF_8));

// Create submission properties
SubmissionProperties properties = new SubmissionProperties(new SubmissionWebhooks("https://your-server.com/webhook/{STATUS}"));
properties.setSandbox(true);

// Action 2 is 'Index Only'
properties.setAction(SubmissionActions.IndexOnly);

// Configure indexing to Private Cloud Hub
SubmissionIndexingRepository repo = new SubmissionIndexingRepository();
repo.setId("6e870e0bb2264");
SubmissionIndexing indexing = new SubmissionIndexing();
// Requires copyleaks-java-sdk SubmissionIndexing.setRepositories (coming soon)
indexing.setRepositories(new SubmissionIndexingRepository[]{ repo });
properties.setIndexing(indexing);

// Create and submit the file
CopyleaksFileSubmissionModel submission = new CopyleaksFileSubmissionModel(base64Content, "exam_template.txt", properties);

Copyleaks.submitFile(authToken, scanId, submission);
System.out.println("Template indexed successfully.");

Make sure to keep track of the scanId (in this case my-template-index) as you will need it for the next step.

Scan with template exclusion

Now that you have a template indexed, you can submit a new document for scanning and tell Copyleaks to exclude the content of the template.Use the properties.exclude.documentTemplateIds field to specify the template ID.

PUT https://api.copyleaks.com/v3/scans/submit/file/student-exam-submission
Content-Type: application/json
Authorization: Bearer <YOUR_AUTH_TOKEN>

{
  "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
  "filename": "student_submission.txt",
  "properties": {
    "action": 0,
    "webhooks": {
      "status": "https://your-server.com/webhook/{STATUS}"
    },
    "exclude": {
      "documentTemplateIds": ["my-template-index"]
    },
    "indexing": {
      "repositories": [
        {
          "id": "your-repo-id",
          "includeMySubmissions": true,
          "includeOthersSubmissions": true
        }
      ],
      "copyleaksDb": false
    },
    "aiGeneratedText": {
      "detect": true
    },
    "sandbox": true
  }
}

curl -X PUT "https://api.copyleaks.com/v3/scans/submit/file/student-exam-submission" \
     -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
           "filename": "student_submission.txt",
           "properties": {
             "action": 0,
             "webhooks": {
               "status": "https://your-server.com/webhook/{STATUS}"
             },
             "exclude": {
               "documentTemplateIds": ["my-template-index"]
             },
             "indexing": {
               "repositories": [
                 {
                   "id": "your-repo-id",
                   "includeMySubmissions": true,
                   "includeOthersSubmissions": true
                 }
               ],
               "copyleaksDb": false
             },
             "aiGeneratedText": {
               "detect": true
             },
             "sandbox": true
           }
         }'

import requests
import base64

# Student submission content
student_content = "This is the student's answer mixed with template text."
base64_content = base64.b64encode(student_content.encode()).decode('utf-8')

url = "https://api.copyleaks.com/v3/scans/submit/file/student-exam-submission"
payload = {
    "base64": base64_content,
    "filename": "student_submission.txt",
    "properties": {
        "action": 0,
        "webhooks": {
            "status": "https://your-server.com/webhook/{STATUS}"
        },
        "exclude": {
            "documentTemplateIds": ["my-template-index"]
        },
        "indexing": {
            "repositories": [
                {
                    "id": "your-repo-id",
                    "includeMySubmissions": True,
                    "includeOthersSubmissions": True
                }
            ],
            "copyleaksDb": False
        },
        "aiGeneratedText": {
            "detect": True
        },
        "sandbox": True
    }
}
headers = {
    "Authorization": "Bearer <YOUR_AUTH_TOKEN>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

const url = 'https://api.copyleaks.com/v3/scans/submit/file/student-exam-submission';
const headers = {
    'Authorization': 'Bearer <YOUR_AUTH_TOKEN>',
    'Content-Type': 'application/json'
};

const data = {
    base64: "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
    filename: "student_template.txt",
    properties: {
        action: 0,
        webhooks: {
            status: "https://your-server.com/webhook/{STATUS}"
        },
        exclude: {
            documentTemplateIds: ["my-template-index"]
        },
        indexing: {
            repositories: [
                {
                    id: "your-repo-id",
                    includeMySubmissions: true,
                    includeOthersSubmissions: true
                }
            ],
            copyleaksDb: false
        },
        aiGeneratedText: {
            detect: true
        },
        sandbox: true
    }
};

axios.put(url, data, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

import classes.Copyleaks;
import models.submissions.CopyleaksFileSubmissionModel;
import models.submissions.properties.*;
import java.util.Base64;
import java.nio.charset.StandardCharsets;

String scanId = "student-exam-submission";
String base64Content = Base64.getEncoder().encodeToString("This is the student's answer mixed with template text.".getBytes(StandardCharsets.UTF_8));

// Create submission properties
SubmissionProperties properties = new SubmissionProperties(new SubmissionWebhooks("https://your-server.com/webhook/{STATUS}"));
properties.setSandbox(true);

// Set document templates to exclude
SubmissionExclude exclude = new SubmissionExclude();
exclude.setDocumentTemplateIds(new String[]{"my-template-index"});
properties.setExclude(exclude);

// Create and submit the file
CopyleaksFileSubmissionModel submission = new CopyleaksFileSubmissionModel(base64Content, "student_submission.txt", properties);

Copyleaks.submitFile(authToken, scanId, submission);
System.out.println("Scan submitted with template exclusion.");

You can provide multiple template IDs in the documentTemplateIds array if you need to exclude content from multiple templates.

Summary

You have just:

Created a template document and indexed it
Submitted a scan with template exclusion
Excluded template text from your plagiarism analysis

Next steps

Check for Plagiarism

Detect plagiarism in text documents using the Copyleaks API. Search billions of sources to find unoriginal content.

Detect AI-Generated Content

Detect AI-generated text via sync or async API calls. This guide covers sync detection, see the Authenticity API Guide for async.

Assess Grammar and Writing Quality

Get writing and grammar suggestions via API. Authenticate, submit text, and access full details in the docs.

Moderate Text

Scan and moderate text content for unsafe or policy-relevant material across 10+ categories.

Get started

Guides

Using the APIs

Concepts

Resources

How it works

Template sourcing

Get started

Before you begin

Installation

Create a template (index a document)

Scan with template exclusion

Summary

Next steps

Check for Plagiarism

Detect AI-Generated Content

Assess Grammar and Writing Quality

Moderate Text

​How it works

​Template sourcing

​Get started

​Before you begin

​Installation

​Login

​Create a template (index a document)

​Scan with template exclusion

​Summary

​Next steps

Check for Plagiarism

Detect AI-Generated Content

Assess Grammar and Writing Quality

Moderate Text

How it works

Template sourcing

Get started

Before you begin

Installation

Login

Create a template (index a document)

Scan with template exclusion

Summary

Next steps