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	Student Submission	What Copyleaks Scans
(Indexed beforehand)	(The file you scan)	(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

1. 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.

2. Installation

   Choose your preferred method for making API calls.

   HTTP

   You can interact with the API using any standard HTTP client.

   For a quicker setup, we provide a Postman collection. See our Postman guide for instructions.

   cURL
   Ubuntu/Debian

   sudo apt-get install curl

   Windows

   Download it from curl.se

   macOS

   brew install curl

   Python

   pip install copyleaks

   JavaScript

   npm install plagiarism-checker

   Java

   Download from Maven

3. Login

   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.

   HTTP

   POST https://id.copyleaks.com/v3/account/login/api
   
   Headers
   Content-Type: application/json
   
   Body
   {
       "email": "[email protected]",
       "key": "00000000-0000-0000-0000-000000000000"
   }

   cURL

   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}\"
     }"

   Python

   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)

   JavaScript

   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();

   Java

   import com.copyleaks.sdk.api.Copyleaks;
   
   String EMAIL_ADDRESS = "[email protected]";
   String API_KEY = "00000000-0000-0000-0000-000000000000";
   
   // Login to Copyleaks
   try {
       String authToken = Copyleaks.login(EMAIL_ADDRESS, API_KEY);
       System.out.println("Logged successfully!\nToken: " + authToken);
   } catch (CommandException 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"
   }

   Note

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

4. 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.

   HTTP

   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

   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
              }
            }'

   Python

   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())

   Node.js

   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));

   Java

   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
   SubmissionIndexing indexing = new SubmissionIndexing();
   SubmissionRepo repo = new SubmissionRepo("6e870e0bb2264");
   repo.setIncludeMySubmissions(true);
   repo.setIncludeOthersSubmissions(true);
   indexing.setRepositories(new SubmissionRepo[]{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.");

   Note

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

5. 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.

   HTTP

   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

   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
              }
            }'

   Python

   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())

   Node.js

   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));

   Java

   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.");

   Tip

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

6. 🎉 Congratulations!

   You have just:

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

What’s Next?

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.