# Submit OCR

> Scan images with textual content to find where the content has been used before and check its originality.

<RequestExample>

```bash title="cURL" icon="terminal"
curl --request PUT \
  --url https://api.copyleaks.com/v3/scans/submit/ocr/my-scan-123 \
  --header 'Authorization: Bearer YOUR_LOGIN_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "base64": "YOUR_BASE64_HERE",
    "filename": "image.jpg",
    "langCode": "en",
    "properties": {
      "webhooks": {
        "status": "https://my-server.com/webhook/{STATUS}"
      },
      "sandbox": true
    }
  }'
```

```python title="Python" icon="python"
import base64
from copyleaks.copyleaks import Copyleaks
from copyleaks.models.submit.document import OcrFileDocument
from copyleaks.models.submit.properties.scan_properties import ScanProperties
from copyleaks.models.submit.properties.submit_webhooks import SubmitWebhooks

auth_token = Copyleaks.login("your@email.address", "YOUR_API_KEY")

with open("image.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode("utf-8")

submission = OcrFileDocument(b64, "image.jpg", "en")
submission.set_properties(ScanProperties(
    webhooks=SubmitWebhooks(status="https://my-server.com/webhook/{STATUS}"),
    sandbox=True,
))

Copyleaks.submit_file_ocr(auth_token, "my-scan-123", submission)
```

```javascript title="JavaScript" icon="square-js"
const { Copyleaks, CopyleaksFileOcrSubmissionModel } = require('plagiarism-checker');
const fs = require('fs');

const copyleaks = new Copyleaks();
const auth = await copyleaks.loginAsync('YOUR_EMAIL', 'YOUR_API_KEY');

const base64Content = fs.readFileSync('image.jpg').toString('base64');
const submission = new CopyleaksFileOcrSubmissionModel(
  'en',
  base64Content,
  'image.jpg',
  {
    sandbox: true,
    webhooks: { status: 'https://my-server.com/webhook/{STATUS}' },
  }
);

await copyleaks.submitFileOcrAsync(auth, 'my-scan-123', submission);
```

```java title="Java" icon="java"
import classes.Copyleaks;
import models.submissions.CopyleaksOcrSubmissionModel;
import models.submissions.properties.*;
import java.util.Base64;
import java.nio.file.*;

String authToken = Copyleaks.login("your@email", "API_KEY");
String b64 = Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get("image.jpg")));

SubmissionWebhooks hooks = new SubmissionWebhooks("https://my-server.com/webhook/{STATUS}");
SubmissionProperties props = new SubmissionProperties(hooks);
props.setSandbox(true);

Copyleaks.submitOCR(authToken, "my-scan-123",
  new CopyleaksOcrSubmissionModel(b64, "image.jpg", "en", props));
```

</RequestExample>

<ResponseExample>

```json 201 Created
{
  "scannedDocument": {
    "scanId": "scan-id32",
    "totalWords": 2,
    "totalExcluded": 0,
    "credits": 0,
    "expectedCredits": 1,
    "creationTime": "2025-08-05T07:19:08.181236Z",
    "metadata": { "filename": "file.jpg" },
    "detectedLanguage": "en"
  },
  "results": {
    "score": { "aggregatedScore": 50.0, "identicalWords": 1 },
    "internet": [
      { "url": "http://example.com/", "id": "2a1b402420", "title": "Example Domain" }
    ]
  },
  "status": 0,
  "developerPayload": ""
}
```

</ResponseExample>

Scan images with textual content to find where the content has been used before and check its originality. Using submit-ocr you can scan various image file types for plagiarism and identify infringed content. Only the textual content in the picture will be scanned and not the graphics. See [supported formats](/reference/actions/miscellaneous/supported-plagiarism-file-types).

<Warning>
**Authentication Required.** You need to login with a user and API key in order to access this method. Add this HTTP header to your request:

**Authorization: Bearer &lt;Your-Login-Token&gt;**
</Warning>

## Request

### Path Parameters

<ParamField path="scanId" type="string" required>
  A unique scan id provided by you. We recommend you use the same id in your database to represent the scan in the Copyleaks database. This will help you to debug incidents. Using the same ID for the same file will help you to avoid network problems that may lead to multiple scans for the same file. Learn more about [the criteria for creating a Scan ID](/concepts/management/choosing-scan-id).

  `>= 3 characters` `<= 36 characters`
</ParamField>

### Headers

```http
Content-Type: application/json
Authorization: Bearer YOUR_LOGIN_TOKEN
```

### Request Body

The request body is a JSON object containing the image file to scan and a `properties` object to configure the scan.

<ParamField body="base64" type="string" required>
  A base64 data string of a file. If you would like to scan plain text, encode it as base64 and submit it.

      Example: `aGVsbG8gd29ybGQ=`
</ParamField>
<ParamField body="filename" type="string" required>
  The name of the file as it will appear in the Copyleaks scan report. Make sure to include the right extension for your filetype.

      `<= 255` characters

      Example: `image.jpg`
</ParamField>
<ParamField body="langCode" type="string" required>
  The language of the text in the image. See [supported languages](/reference/actions/miscellaneous/ocr-supported-languages).

      Example: `en`
</ParamField>
<ParamField body="properties" type="object" required>
  Configuration options for the scan.
  <Expandable title="properties">
    <ScanSubmitProperties />
  </Expandable>
</ParamField>

<Note title="Integration Testing">
For testing purposes, use sandbox mode, which does not consume credits.
</Note>

## Responses

<Tabs>
  <Tab title="201">
    <Check>**201 Created** - The scan was successfully created and is now processing.</Check>

    ```json
    {
      "scannedDocument": {
        "scanId": "scan-id32",
        "totalWords": 2,
        "totalExcluded": 0,
        "credits": 0,
        "expectedCredits": 1,
        "creationTime": "2025-08-05T07:19:08.181236Z",
        "metadata": {
          "filename": "file.jpg"
        },
        "detectedLanguage": "en"
      },
      "status": 0,
      "developerPayload": ""
    }
    ```
  </Tab>
  <Tab title="400">
    <Warning>**400 Bad Request** - The filename field is required.</Warning>
  </Tab>
  <Tab title="401">
    <Warning>**401 Unauthorized** - Authentication failed or API key is invalid.</Warning>
  </Tab>
  <Tab title="409">
    <Warning>**409 Conflict** - A scan with the same Id already exists in the system.</Warning>
  </Tab>
  <Tab title="429">
    <Warning>**429 Too Many Requests** - Rate limit exceeded. Please retry after the specified time.</Warning>
  </Tab>
</Tabs>