Table of contents

Thanks for Downloading Dynamic Web TWAIN 30-Day Trial!

Your download will start shortly. If your download does not begin, click here to retry.

RESTful API

This is the comprehensive reference for the Dynamic Web TWAIN RESTful API. By default, all APIs use the root URL https://127.0.0.1:18623/api set by the Dynamic Web TWAIN Service. (can also use http://127.0.0.1:18622/api) Read about how to alter the address along with a developer walkthrough in our user guide.

Server Control

Endpoint Method Description
/server GET Get server settings
/server PATCH Update specified server settings
/server/version GET Get server API version

Scanner Control

Endpoint Method Description
/device/scanners GET Get list of scanners
/device/scanners/jobs POST Create a scan job
/device/scanners/jobs/{jobuid} GET Get status of a scan job
/device/scanners/jobs/{jobuid} PATCH Update status of a scan job
/device/scanners/jobs/{jobuid} DELETE Delete a scan job
/device/scanners/jobs/{jobuid}/scanner/capabilities GET Retrieve scanner capabilities specified in a scan job
/device/scanners/jobs/{jobuid}/scanner/settings GET Retrieve settings of scanner specified in a scan job.
/device/scanners/jobs/{jobuid}/next-page-info GET Get information of the next page in a scan job
/device/scanners/jobs/{jobuid}/next-page GET Get the page in a scan job

Document Management

Endpoint Method Description
/storage/documents POST Create a new document for storage
/storage/documents/{documentuid} GET Get info of a stored document
/storage/documents/{documentuid} DELETE Delete a stored document
/storage/documents/{documentuid}/content GET Get content of a stored document
/storage/documents/{documentuid}/pages POST Insert pages into a stored document
/storage/documents/{documentuid}/pages/{param} DELETE Delete a page in a stored document

Document Processing

Endpoint Method Description
/process/read-barcode POST Read a barcode on a page scanned from a specified source
/process/check-blank POST Check if a page scanned from a specified source is blank

Server Control

GET /server

Get the server settings. Some settings require administrator privileges to retrieve.

Parameters

None

Request Example

Only valid request:

const url = new URL("https://127.0.0.1:18623/api");
const pathSegments = ['server'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let requestOptions = {
   method: 'GET',
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. ServerSettings
405 Method Not Allowed Method not allowed. Error

Response Examples

200 Response
{
  "logLevel": 1
}
405 Response
{
  "code": -2112,
  "message": "This endpoint only supports GET, PATCH.",
  "statusCode": 405
}

PATCH /server

Update specified server settings. Some settings require administrator privileges to modify.

Parameters

Name Location Type Required Restrictions Description
logLevel body ServerSettingsInput no none  

Request Example

Set DWT Service log verbosity to maximum:

const url = new URL("https://127.0.0.1:18623/api");
const pathSegments = ['server'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

let raw = JSON.stringify({ logLevel: 30 });

let requestOptions = {
   method: 'PATCH',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. ServerSettings
400 Bad Request Bad request, e.g. parameter is invalid. Error
405 Method Not Allowed Method not allowed. Error

Response Examples

200 Response:

{
  "logLevel": 1
}

400 Response:

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET, PATCH.",
  "statusCode": 405
}

GET /server/version

Get the API version of the server.

Parameters

None

Request Example

Only valid request to get the server API version:

const url = new URL("https://127.0.0.1:18623/api");
const pathSegments = ['server', 'version'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let requestOptions = {
   method: 'GET',
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. VersionInfo
405 Method Not Allowed Method not allowed. Error

Response Examples

200 Response:

{
  "version": "20240719",
  "compatible": true
}

405 Response:

{
  "code": -2112,
  "message": "This endpoint only supports GET.",
  "statusCode": 405
}

Scanner Control

GET /device/scanners

Get a list of scanners from the host. By default this returns all scanners, but you can optionally request scanners specified by protocols. Scanner protocols are enumerated with the Dynamsoft.DWT.EnumDWT_DeviceType.

Parameters

Name Location Type Required Restrictions Description
type query ScannerType no One or a combination of:
- 0x10: TWAINSCANNER
- 0x20: WIASCANNER
- 0x40: TWAINX64SCANNER
- 0x80: ICASCANNER
- 0x100: SANESCANNER
- 0x200: ESCLSCANNER
- 0x400: WIFIDIRECTSCANNER
- 0x800: WIATWAINSCANNER
Device type(s), can be one or a combination, specifies TWAIN/TWAIN64/WIA/ICA/SANE by default.

Request Example

Get the list of all TWAIN/TWAIN64/WIA/ICA/SANE scanners:

const url = new URL("https://127.0.0.1:18623/api");
const pathSegments = ['device', 'scanners'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let requestOptions = {
   method: 'GET',
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. Scanner[]
400 Bad Request Bad request, e.g. parameter is invalid. Error
405 Method Not Allowed Method not allowed. Error

Response Examples

200 Response:

[
  {
    "name": "TWAIN2 FreeImage Software Scanner",
    "type": 16,
    "device": "{\"deviceInfo\":{\"Manufacturer\":\"VFdBSU4gV29ya2luZyBHcm91cA==\",\"ProductFamily\":\"U29mdHdhcmUgU2Nhbg==\",\"ProductName\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\",\"ProtocolMajor\":2,\"ProtocolMinor\":1,\"SupportedGroups\":0,\"Version\":{\"Country\":1,\"Info\":\"Mi4xLjMgc2FtcGxlIHJlbGVhc2UgMzJiaXQ=\",\"Language\":2,\"MajorNum\":2,\"MinorNum\":1}},\"deviceType\":16,\"isSystemDefaultPrinter\":false,\"name\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\"}"
  }
]

400 Response:

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

405 Response:

{
  "code": -2112,
  "message": "This endpoint only supports GET.",
  "statusCode": 405
}

POST /device/scanners/jobs

Create a scan job.

You can scan with a specified scanner, or use the latest scanner by default. This API provides an extensive set of parameters to:

  • Set scanner capabilities
  • Show the scanner UI when the client is on the same machine that the Dynamic Web TWAIN Service is running on.
  • Get the scanned image with the jobuid once the scan job completes, or save to a specified document
  • Create a pending job with the specified scanner. (every scanner can only have one pending job) We recommend creating pending jobs for shared scanners. By default, requests for the job are bound to the domain of the client that created the scan job.

The config, settings, and capability all provide different ways to specify the same scan settings for the scan job. These settings override each other in predicable ways as outlined in CreateScanJobOptions, but we recommend only using one of the three parameters for clarity, whichever is most convenient to you.

After creating a scan job, the job either:

  1. completes successfully,
  2. hangs indefinitely,
  3. times out once it hits the jobTimeout value if set,
  4. or gets deleted if you send a delete request.

Parameters

Name Location Type Required Description
X-DICS-LICENSE-KEY header string yes DWT license key with the RESTful API module - contact our sales team for a full license, or get a 30-day free trial.
CreateScanJobOptions body CreateScanJobOptions no none

Request Example

Start a scan job as pending and check the feeder. The device and settings values were obtained from earlier /device/scanners/twain/settings and /device/scanners calls. Various scanning configurations are set with the config parameter:

const url = new URL("https://127.0.0.1:18623/api");
const pathSegments = ['device', 'scanners', 'jobs'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("X-DICS-LICENSE-KEY", "YOUR_LICENSE_KEY_HERE");
myHeaders.append("Content-Type", "application/json");

let raw = JSON.stringify({
  "autoRun": false,
  "device": "{\"deviceInfo\":{\"Manufacturer\":\"VFdBSU4gV29ya2luZyBHcm91cA==\",\"ProductFamily\":\"U29mdHdhcmUgU2Nhbg==\",\"ProductName\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\",\"ProtocolMajor\":2,\"ProtocolMinor\":1,\"SupportedGroups\":0,\"Version\":{\"Country\":1,\"Info\":\"Mi4xLjMgc2FtcGxlIHJlbGVhc2UgMzJiaXQ=\",\"Language\":2,\"MajorNum\":2,\"MinorNum\":1}},\"deviceType\":16,\"isSystemDefaultPrinter\":false,\"name\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\"}",
  "name": "TWAIN2 FreeImage Software Scanner",
  "checkFeederLoaded": true,
  "config": {
    "PixelType": 1,
    "Resolution": 300,
    "IfFeederEnabled": true,
    "IfDuplexEnabled": false,
    "IfGetImageInfo": true,
    "IfGetExtImageInfo": true,
    "extendedImageInfoQueryLevel": 0,
    "IfCloseSourceAfterAcquire": true,
    "XferCount": 11
  },
  "caps": {
    "exception": "ignore",
    "capabilities": [
      {
        "capability": 4355,
        "curValue": 500
      }
    ]
  },
  "settings": "Rfj6pIMTNkCu3BfDloGItBAAAAACEAAABgAFAAEAAAAQAAAAExAAAAYABQAAAAAAEAAAAAcQAAAGAAUAAQAAABAAAAArEQAABAAFABgAAAAQAAAAHBEAAAQABQAAAAAAEAAAAAABAAAEAAUAAAAAABwAAAAUEQAACAAFAPgqAAAAAAAANCEAAAAAAAAQAAAADBEAAAQABQACAAAAEAAAAB8RAAAEAAUAAAAAABAAAAABAQAABAAFAAIAAAAQAAAAIBEAAAQABQAAAAAAEAAAACIRAAAEAAUAAwAAABAAAAAQEQAABAAFAAAAAAAQAAAAAgEAAAQABQAAAAAAEAAAABgRAAAHAAUAAABIQxAAAAAZEQAABwAFAAAASEMQAAAAIxEAAAcABQAAAABDEAAAAAMRAAAHAAUAAAAAABAAAAABEQAABwAFAAAAAAAQAAAACBEAAAcABQAAAIA/EAAAAAGAAAAGAAUAAAAAAA=="
});

let requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
201 Created Successful operation. ScannerJob
400 Bad Request Bad request, e.g. parameter is invalid. Error
403 Forbidden License is invalid. Error
405 Method Not Allowed Method not allowed. Error
423 Locked Source is connected to maximum supported number of applications. Error

Response Examples

201 Response:

{
  "jobuid": "B3701DC5-86D3-44B6-A8A1-FF0B5D43FD86",
  "status": "pending",
  "scanner": {
    "name": "TWAIN2 FreeImage Software Scanner",
    "type": 16,
    "device": "{\"deviceInfo\":{\"Manufacturer\":\"VFdBSU4gV29ya2luZyBHcm91cA==\",\"ProductFamily\":\"U29mdHdhcmUgU2Nhbg==\",\"ProductName\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\",\"ProtocolMajor\":2,\"ProtocolMinor\":1,\"SupportedGroups\":0,\"Version\":{\"Country\":1,\"Info\":\"Mi4xLjMgc2FtcGxlIHJlbGVhc2UgMzJiaXQ=\",\"Language\":2,\"MajorNum\":2,\"MinorNum\":1}},\"deviceType\":16,\"isSystemDefaultPrinter\":false,\"name\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\"}"
  }
}

400 Response:

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

403 Response:

{
  "code": -2800,
  "message": "The current product key is empty or invalid. Please contact the site administrator.",
  "statusCode": 403
}

405 Response:

{
  "code": -2112,
  "message": "This endpoint only supports POST.",
  "statusCode": 405
}

423 Response:

{
  "code": -1004,
  "message": "Source is connected to maximum supported number of applications.",
  "statusCode": 423
}

GET /device/scanners/jobs/{jobuid}

Get the status of a scan job provided its jobuid.

Obtain the jobuid from the response of the POST /device/scanners/jobs scan job creation request.

Parameters

Name Location Type Required Restrictions Description
jobuid path string yes none Unique identifier for the scan job, obtained from the POST /device/scanners/jobs scan job creation request.

Request Example

Request the status of a previously-requested scan job:

const url = new URL("https://127.0.0.1:18623/api");
const jobuid = `B3701DC5-86D3-44B6-A8A1-FF0B5D43FD86`;
const pathSegments = ['device', 'scanners', 'jobs', jobuid];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

let requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. ScannerJobInfo
404 Not Found The provided job UID is invalid. Error
405 Method Not Allowed Method not allowed. Error
410 Gone Job was deleted. Return 404 instead upon restart of the Dynamic Web TWAIN Service as that clears all job info. Error

Response Examples

200 Response

{
  "status": "pending",
  "code": "0",
  "message": "Successful"
}

404 Response

{
  "code": -1034,
  "message": "The provided job UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET, PATCH, DELETE.",
  "statusCode": 405
}

410 Response

{
  "code": -1034,
  "message": "Job was deleted.",
  "statusCode": 410
}

PATCH /device/scanners/jobs/{jobuid}

Update status of a scan job given its jobuid.

Update the status of the job while the job is in the pending state. This request is ignored if the job is in any other state. Obtain the jobuid from the response of the POST /device/scanners/jobs scan job creation request.

Parameters

Name Location Type Required Restrictions Description
jobuid path string yes none Unique identifier for the scan job, obtained from the POST /device/scanners/jobs scan job creation request.
status body string yes - running: running
- canceled: canceled
Default value running - update the job status. When the job is running, the only acceptable value is canceled to cancel the job. When the job is pending, the only acceptable value is running to start the job.

Request Example

Start a pending job:

const url = new URL("https://127.0.0.1:18623/api");
const jobuid = `B3701DC5-86D3-44B6-A8A1-FF0B5D43FD86`;
const pathSegments = ['device', 'scanners', 'jobs', jobuid];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

let raw = JSON.stringify({
  status: 'running'
})

let requestOptions = {
   method: 'PATCH',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. ScannerJobStatus
400 Bad Request Bad request, e.g. parameter is invalid. Error
404 Not Found The provided job UID is invalid. Error
405 Method Not Allowed Method not allowed. Error
409 Conflict Attempted to cancel non-pending or non-running job, or update a non-pending job to running. Error
410 Gone Job was deleted. Return 404 instead upon restart of the Dynamic Web TWAIN Service as that clears all job info. Error

Response Examples

200 Response

{
  "status": "running"
}

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

404 Response

{
  "code": -1034,
  "message": "The provided job UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET, PATCH, DELETE.",
  "statusCode": 405
}

409 Response

{
  "code": -1011,
  "message": "Cannot cancel non-pending or non-running job, or update a non-pending job to running.",
  "statusCode": 409
}

410 Response

{
  "code": -1034,
  "message": "Job was deleted.",
  "statusCode": 410
}

DELETE /device/scanners/jobs/{jobuid}

Delete a scan job, provided its jobuid.

if the job is running, cancel then delete the scan job, including all scanned documents. Obtain the jobuid from the response of the POST /device/scanners/jobs scan job creation request.

Parameters

Name Location Type Required Restrictions Description
jobuid path string yes none Unique identifier for the scan job, obtained from the POST /device/scanners/jobs scan job creation request.

Request Example

Only valid request syntax (to cancel a scan job):

const url = new URL("https://127.0.0.1:18623/api");
const jobuid = `B3701DC5-86D3-44B6-A8A1-FF0B5D43FD86`;
const pathSegments = ['device', 'scanners', 'jobs', jobuid];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let requestOptions = {
   method: 'DELETE',
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
204 No Content Successful operation. None
404 Not Found The provided job UID is invalid. Error
405 Method Not Allowed Method not allowed. Error
410 Gone Job already deleted. Error

Response Examples

404 Response

{
  "code": -1034,
  "message": "The provided job UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET, PATCH, DELETE.",
  "statusCode": 405
}

410 Response

{
  "code": -1034,
  "message": "Job already deleted.",
  "statusCode": 410
}

GET /device/scanners/jobs/{jobuid}/scanner/capabilities

Retrieve the capabilities of the scanner specified in the scan job, provided its jobuid.

This API can only be called when the job is in a pending state, hence you must create the job with autoRun set to false for a valid response. By default this API returns all capabilities, but you can select specific capabilities with comma separated values using caps. See the capability enumerations for more information. Obtain the jobuid from the response of the POST /device/scanners/jobs scan job creation request.

Parameters

Name Location Type Required Restrictions Description
jobuid path string yes none Unique identifier for the scan job, obtained from the POST /device/scanners/jobs scan job creation request.
caps query string no See list of all capabilities here. Comma-separated list of enumerated capabilities to request - leave empty to request all capabilities.

Request Example

Query duplex scanning (value 4114) and auto-feed (value 4103) capabilities of the specified job:

const url = new URL("https://127.0.0.1:18623/api");
const jobuid = `B3701DC5-86D3-44B6-A8A1-FF0B5D43FD86`;
const pathSegments = ['device', 'scanners', 'jobs', jobuid, 'scanner', 'capabilities'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

url.searchParams.append('caps', '4114,4103');

let requestOptions = {
   method: 'GET',
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. CapabilityDetails
400 Bad Request Bad request, e.g. parameter is invalid. Error
404 Not Found The provided job UID is invalid. Error
405 Method Not Allowed Method not allowed. Error
409 Conflict Cannot be called when job is not pending. Error
410 Gone Job was deleted. Return 404 instead upon restart of the Dynamic Web TWAIN Service as that clears all job info. Error

Response Examples

200 Response

[
  {}
]

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

404 Response

{
  "code": -1034,
  "message": "The provided job UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET.",
  "statusCode": 405
}

409 Response

{
  "code": -1011,
  "message": "Cannot be called when job is not pending.",
  "statusCode": 409
}

410 Response

{
  "code": -1034,
  "message": "Job was deleted.",
  "statusCode": 410
}

GET /device/scanners/jobs/{jobuid}/scanner/settings

Retrieve the settings of the scanner specified in the scan job, provided the jobuid.

This request only supports TWAIN scanners, and is only valid when the job is pending. This API relies on EnableSourceUI to show the scanner UI if enabled by the showui parameter. Obtain the jobuid from the response of the POST /device/scanners/jobs scan job creation request.

Parameters

Name Location Type Required Restrictions Description
jobuid path string yes none Unique identifier for the scan job, obtained from the POST /device/scanners/jobs scan job creation request.
showui query boolean no none Default value true - shows the scanner UI.

Request Example

Get the settings of the scanner performing a scan job and show the UI

const url = new URL("https://127.0.0.1:18623/api");
const jobuid = `B3701DC5-86D3-44B6-A8A1-FF0B5D43FD86`;
const pathSegments = ['device', 'scanners', 'jobs', jobuid, 'scanner', 'settings'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

const params = new URLSearchParams();
params.append(`showui`, 'true');

let requestOptions = {
   method: 'GET',
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. base64 encoded string
400 Bad Request Bad request, e.g. parameter is invalid. Error
404 Not Found The provided job UID is invalid. Error
405 Method Not Allowed Method not allowed. Error
409 Conflict The job is not pending. Error
410 Gone The job was deleted. Error

Response Examples

200 Response

{
  "settings": "Rfj6pIMTNkCu3BfDloGItBAAAAACEAAABgAFAAEAAAAQAAAAExAAAAYABQAAAAAAEAAAAAcQAAAGAAUAAQAAABAAAAArEQAABAAFABgAAAAQAAAAHBEAAAQABQAAAAAAEAAAAAABAAAEAAUAAAAAABwAAAAUEQAACAAFAPgqAAAAAAAANCEAAAAAAAAQAAAADBEAAAQABQACAAAAEAAAAB8RAAAEAAUAAAAAABAAAAABAQAABAAFAAIAAAAQAAAAIBEAAAQABQAAAAAAEAAAACIRAAAEAAUAAwAAABAAAAAQEQAABAAFAAAAAAAQAAAAAgEAAAQABQAAAAAAEAAAABgRAAAHAAUAAABIQxAAAAAZEQAABwAFAAAASEMQAAAAIxEAAAcABQAAAABDEAAAAAMRAAAHAAUAAAAAABAAAAABEQAABwAFAAAAAAAQAAAACBEAAAcABQAAAIA/EAAAAAGAAAAGAAUAAAAAAA=="
}

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

404 Response

{
  "code": -1034,
  "message": "The provided job UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET.",
  "statusCode": 405
}

409 Response

{
  "code": -1011,
  "message": "The job is not pending.",
  "statusCode": 409
}

410 Response

{
  "code": -1034,
  "message": "Invalid Value.",
  "statusCode": 410
}

GET /device/scanners/jobs/{jobuid}/next-page-info

Get information of the next page in a scan job, provided its jobuid.

This will not return until the scanned page is ready. If the response code is 200, you can keep calling this API until a code 204 response. Obtain the jobuid from the response of the POST /device/scanners/jobs scan job creation request.

Parameters

Name Location Type Required Restrictions Description
jobuid path string yes none Unique identifier for the scan job, obtained from the POST /device/scanners/jobs scan job creation request.

Request Example

const url = new URL("https://127.0.0.1:18623/api");
const jobuid = `B3701DC5-86D3-44B6-A8A1-FF0B5D43FD86`;
const pathSegments = ['device', 'scanners', 'jobs', jobuid, 'next-page-info'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let requestOptions = {
   method: 'GET',
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK successful operation. Also returns the image url; if scanning to a document, also return document UID and page UID. OutputInfo
204 No Content No more pages, scan done. None
404 Not Found The provided job UID is invalid. Error
405 Method Not Allowed Method not allowed. Error
410 Gone Job was deleted. Return 404 instead upon restart of the Dynamic Web TWAIN Service as that clears all job info. Inline

Response Examples

200 Response

[
  {
    "extendedImageInfo": {},
    "imageId": 1,
    "imageInfo": {
      "BitsPerPixel": 24,
      "BitsPerSample": [
        8,
        8,
        8,
        0,
        0,
        0,
        0,
        0
      ],
      "Compression": 0,
      "ImageLayout": {
        "DocumentNumber": 1,
        "Frame": {
          "Bottom": 11,
          "Left": 0,
          "Right": 8.5,
          "Top": 0
        },
        "FrameNumber": 0,
        "PageNumber": 1
      },
      "ImageLength": 2200,
      "ImageWidth": 1700,
      "PixelType": 2,
      "Planar": false,
      "SamplesPerPixel": 3,
      "XResolution": 200,
      "YResolution": 200
    },
    "imageuid": "1951d65a72b1",
    "url": "https://127.0.0.1:18623/api/device/scanners/jobs/510dadf2-7e29-4172-80f1-49fa5d2ea0bf/next-page?page=1951d65a72b1"
  }
]

404 Response

{
  "code": -1034,
  "message": "The provided job UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET.",
  "statusCode": 405
}

410 Response

{
  "code": -1034,
  "message": "Job was deleted.",
  "statusCode": 410
}

GET /device/scanners/jobs/{jobuid}/next-page

Get the page in a scan job, provided its jobuid.

Use the type parameter to set the format of the image as either jpeg or png. This API will not return until the scanned page is ready. If the response code is 200, you can keep calling this API until a code 204 response. Obtain the jobuid from the response of the POST /device/scanners/jobs scan job creation request.

Parameters

Name Location Type Required Restrictions Description
jobuid path string yes none Unique identifier for the scan job, obtained from the POST /device/scanners/jobs scan job creation request.
type query string no - image/png: PNG
- image/jpeg: JPEG
Default value image/png - the image format of the page, either image/png or image/jpeg.

Request Example

Get the next page from a scan job as a png:

const url = new URL("https://127.0.0.1:18623/api");
const jobuid = `B3701DC5-86D3-44B6-A8A1-FF0B5D43FD86`;
const pathSegments = ['device', 'scanners', 'jobs', jobuid, 'next-page'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

const params = new URLSearchParams();
params.append(`type`, 'image/png');

url.search = params.toString();
let requestOptions = {
   method: 'GET',
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. Return image/png or image/jpeg stream. binary data stream
204 No Content No more pages, scan done. None
400 Bad Request Bad request, e.g. parameter is invalid. Error
404 Not Found The provided job UID is invalid. Error
405 Method Not Allowed Method not allowed. Error
410 Gone Job was deleted. Return 404 instead upon restart of the Dynamic Web TWAIN Service as that clears all job info. Error

Response Examples

200 Response

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

404 Response

{
  "code": -1034,
  "message": "The provided job UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET.",
  "statusCode": 405
}

410 Response

{
  "code": -1034,
  "message": "Job was deleted.",
  "statusCode": 410
}

Document Management

POST /storage/documents

Create a new document for storage.

The document is stored in the Dynamic Web TWAIN Service working directory, and all content is optionally encrypted with the supplied password string. The request returns a document uid upon successfully creating the document.

Parameters

Name Location Type Required Restrictions Description
CreateDocumentOptions body CreateDocumentOptions no none  

Responses

HTTP Status Code Meaning Description Data Schema
201 Created Successful operation. DocumentInfo
400 Bad Request Bad request, e.g. parameter is invalid. Error
405 Method Not Allowed Method not allowed. Error

Request Example

Create a new document with a password:

const url = new URL("https://127.0.0.1:18623/api");
const pathSegments = ['storage', 'documents'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

let raw = JSON.stringify({ password: 'myPassword' });

let requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Response Examples

201 Response

{
  "uid": "190807444d76",
  "pages": []
}

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports POST.",
  "statusCode": 405
}

GET /storage/documents/{documentuid}

Get info of a document stored in the working directory of the Dynamic Web TWAIN Service, provided the documentuid.

This information consists of the documentuid and an array of page uid. If the document is password-encrypted, this request must provide the password for access. Obtain the document from the response of the POST storage/documents document creation request.

Parameters

Name Location Type Required Restrictions Description
documentuid path string yes none The UID of the document.
X-DICS-DOC-PASSWORD header string no length <= 32 characters The password of the document (32 characters max).

Request Example

Get document information for an encrypted document:

const url = new URL("https://127.0.0.1:18623/api");
const documentuid = `190807444d76`;
const pathSegments = ['storage', 'documents', documentuid];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("X-DICS-DOC-PASSWORD", "myPassword");

let requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation DocumentInfo
400 Bad Request Bad request, e.g. parameter is invalid. Error
403 Forbidden none Error
404 Not Found The provided document UID is invalid. Error
405 Method Not Allowed Method not allowed. Error

Response Examples

200 Response

{
  "uid": "190807444d76",
  "pages": [
    {
      "uid": "190817548d70"
    },
    {
      "uid": "190817648270"
    }
  ]
}

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

403 Response

{
  "code": -1043,
  "message": "The password is not valid.",
  "statusCode": 403
}

404 Response

{
  "code": -1040,
  "message": "The provided UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET, DELETE.",
  "statusCode": 405
}

DELETE /storage/documents/{documentuid}

Delete a stored document.

Delete a document stored in the working directory of the Dynamic Web TWAIN Service. If the document is password-encrypted, this request must provide the password for access. Obtain the document from the response of the POST storage/documents document creation request.

Parameters

Name Location Type Required Restrictions Description
documentuid path string yes none The UID of the document.
X-DICS-DOC-PASSWORD header string no length <= 32 characters The password of the document (32 characters max).

Request Example

Delete an encrypted document:

const url = new URL("https://127.0.0.1:18623/api");
const documentuid = `190807444d76`;
const pathSegments = ['storage', 'documents', documentuid];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("X-DICS-DOC-PASSWORD", "myPassword");

let requestOptions = {
   method: 'DELETE',
   headers: myHeaders,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
204 No Content Successful operation. None
400 Bad Request Bad request, e.g. parameter is invalid. Error
403 Forbidden The password is not valid. Error
404 Not Found The provided document UID is invalid. Error
405 Method Not Allowed Method not allowed. Error

Response Examples

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

403 Response

{
  "code": -1043,
  "message": "The password is not valid.",
  "statusCode": 403
}

404 Response

{
  "code": -1040,
  "message": "The provided document UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET, DELETE.",
  "statusCode": 405
}

GET /storage/documents/{documentuid}/content

Get pages of a stored document, provided its documentuid.

Get pages of a document stored in the working directory of the Dynamic Web TWAIN Service. By default this API retrieves the pages as a single PDF, but can also provide a multi-page TIFF file, or retrieve pages separately asJPEG or PNG files. This API can select multiple pages by page uid or page index. If no pages are specified and the format is either PDF or TIFF, it retrieves all pages in the document as one file. The API can also specify file attributes such as file encryption password and compression level, as well as file metadata such as creation date, author name, and key words. If the document is password-encrypted, this request must provide the password for access. Obtain the document from the response of the POST storage/documents document creation request.

Parameters

Name Location Type Required Restrictions Description
documentuid path string yes none The UID of the document.
type query string no - image/jpeg: JPEG
- image/png: PNG
- image/tiff: TIFF
- application/pdf: PDF
Default value application/pdf - output mime type.
quality query integer(int32) no - 0 <= quality <= 100 if compression is 6
- Empty if compression is not 6
Default value 80 - compression from 0 to 100, higher is more compression. This is only valid for the PDF jpeg/jpeg2000 compression method.
pages query string no - Comma-separated integers: page indices
- Comma-separated UIDs: page UIDs
Default value '' - comma-separated page identifiers - either indices or uid, e.g. pages=5,2,1 if using indices. If no pages are specified and the output type is either image/png or image/jpeg, only return the first page; if type is image/tiff or application/pdf, return all pages in the document.
author query string no none Default value '' - author name.
compression query integer(int32) no - 0: PDF_AUTO
- 2: PDF_FAX4
- 3: PDF_LZW
- 5: PDF_JPEG
- 6: PDF_JP2000
- 7: PDF_JBIG2
- 0: TIFF_AUTO
- 1: TIFF_NONE
- 2: TIFF_RLE
- 3: TIFF_FAX3
- 3: TIFF_T4
- 4: TIFF_FAX4
- 4: TIFF_T6
- 5: TIFF_LZW
- 7: TIFF_JPEG
- 32773: TIFF_PACKBITS
Default value 0 - compression type for PDF and TIFF. The default value 0 corresponds to auto-compression. See the enumerations for TIFF and PDF for valid compression methods.
pageType query integer(int32) no - 0: Page_Default
- 1: Page_Custom
- 2: Page_A4
- 3: Page_A4_Reverse
- 4: Page_A3
- 5: Page_A3_Reverse
- 6: Page_Letter
- 7: Page_Letter_Reverse
- 8: Page_Legal
- 9: Page_Legal_Reverse
Default value 0 - standard dimensions for the page. See EnumDWT_CapSupportedSizes for more details.
creator query string no none Default value '' - creator name.
creationDate query string no none Default value '' - creation date.
keyWords query string no none Default value '' - key words.
modifiedDate query string no none Default value '' - modification date.
producer query string no none Default value '' - producer name.
subject query string no none Default value '' - subject.
title query string no none Default value '' - title.
version query string no none Default value 1.5 - version.
password query string no length <= 32 characters Default value '' - PDF file encryption password. The file is unencrypted by default. Note that this is distinct from the document password given by X-DICS-DOC-PASSWORD.
X-DICS-DOC-PASSWORD header string no length <= 32 characters The password of the document (32 characters max).

Request Example

Get two pages (by page uid) of a password-protected document as a TIFF file. Set a file password and a compression level of 50%:

const url = new URL("https://127.0.0.1:18623/api");
const documentuid = `190807444d76`;
const pathSegments = ['storage', 'documents', documentuid];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("X-DICS-DOC-PASSWORD", "myPassword");

let raw = JSON.stringify({
  pages: '190817548d70,190817648270',
  password: 'myFilePassword',
  quality: 50
  });

let requestOptions = {
   method: 'GET',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. binary data stream
400 Bad Request Bad request, e.g. parameter is invalid. Error
403 Forbidden The password is not valid. Error
404 Not Found The provided document UID is invalid. Error
405 Method Not Allowed Method not allowed. Error

Response Examples

200 Response

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

403 Response

{
  "code": -1043,
  "message": "The password is not valid.",
  "statusCode": 403
}

404 Response

{
  "code": -1040,
  "message": "The provided document UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports GET.",
  "statusCode": 405
}

POST /storage/documents/{documentuid}/pages

Insert pages into a stored document, provided its documentuid.

This API is used to insert scanned pages from a scan job to a document stored in the working directory of the Dynamic Web TWAIN Service. The API appends pages to the end of the document by default, though it can specify an insertion index. Obtain the document from the response of the POST storage/documents document creation request.

Parameters

Name Location Type Required Restrictions Description
documentuid path string yes none The UID of the document.
X-DICS-DOC-PASSWORD header string no length <= 32 characters The password of the document (32 characters max).
insertPos body number no 0 < insertPos <= document page count The insertion index that the new pages will be inserted in front of, hence it must be a positive integer. If this is not set or is invalid, insert the pages at the end of the document.
source body string yes Scan job URL Image source URL from the scan job, e.g. https://127.0.0.1:18623/api/device/scanners/jobs/dd40716d-48d1-4d32-89f7-1d53f9665d91/next-page?page=19522d0c5282.

Request Example:

Insert scanned pages from a scan job to the beginning of a stored document:

const url = new URL("https://127.0.0.1:18623/api");
const documentuid = `190807444d76`;
const pathSegments = ['storage', 'documents', documentuid, 'pages'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("X-DICS-DOC-PASSWORD", "myPassword");

let raw = JSON.stringify({
  insertPos: 1,
  source: 'https://127.0.0.1:18623/api/device/scanners/jobs/dd40716d-48d1-4d32-89f7-1d53f9665d91/next-page?page=19522d0c5282',
  });

let requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Page Inserted successfully. DocumentInfo
400 Bad Request Bad request, e.g. parameter is invalid. Error
403 Forbidden The password is not valid. Error
404 Not Found The provided document UID is invalid. Error
405 Method Not Allowed Method not allowed. Error

Response Examples

200 Response

{
  "uid": "190807444d76",
  "pages": [
    {
      "uid": "190817548d70"
    },
    {
      "uid": "190818458d85"
    }
  ]
}

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

403 Response

{
  "code": -1043,
  "message": "The password is not valid.",
  "statusCode": 403
}

404 Response

{
  "code": -1040,
  "message": "The provided document UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports POST.",
  "statusCode": 405
}

DELETE /storage/documents/{documentuid}/pages/{param}

Delete a page in a stored document, provided its documentuid and page uid/index.

Parameters

Name Location Type Required Restrictions Description
documentuid path string yes none The UID of the document.
param path string yes - None-negative integer less than page count: page index
- valid page UID: page UID
UID of the page or 0-based page index.
X-DICS-DOC-PASSWORD header string no length <= 32 characters The password of the document (32 characters max).

Request Example:

Delete the third page stored in a password-encrypted document:

const url = new URL("https://127.0.0.1:18623/api");
const documentuid = `190807444d76`;
const param = '2';
const pathSegments = ['storage', 'documents', documentuid, 'pages', param];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("X-DICS-DOC-PASSWORD", "myPassword");

let requestOptions = {
   method: 'DELETE',
   headers: myHeaders,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
204 No Content Page removed successfully. None
400 Bad Request Bad request, e.g. parameter is invalid. Error
403 Forbidden The password is not valid. Error
404 Not Found The provided page UID is invalid. Error
405 Method Not Allowed Method not allowed Error

Response Examples

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

403 Response

{
  "code": -1043,
  "message": "The password is not valid.",
  "statusCode": 403
}

404 Response

{
  "code": -1040,
  "message": "The provided page UID is invalid.",
  "statusCode": 404
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports DELETE.",
  "statusCode": 405
}

Document Processing

POST /process/read-barcode

Create a new document process to read a barcode on a scanned page.

Barcode scanning requires a valid Barcode Reader Add-On license. Blank page detection is only supported on Windows.

Parameters

Name Location Type Required Restrictions Description
X-DICS-LICENSE-KEY header string yes none A DWT license key with the Barcode Reader and RESTful API module. Contact our sales team for a full license, or get a 30-day free trial.
source body string yes Scan job URL Image source URL from the scan job, e.g. https://127.0.0.1:18623/api/device/scanners/jobs/dd40716d-48d1-4d32-89f7-1d53f9665d91/next-page?page=19522d0c5282.
settings body string Valid barcode reading template JSON - see RuntimeSettings for more details no Barcode reader template settings. Defaults to the BestCoverage setting by default. The basic settings are BestCoverage, BestSpeed, and Balance. Read the Barcode Reader Add-On guide for details on basic settings and advanced scanning templates.

Request Example:

Read a barcode on a page from a scan job with the “best speed” barcode reader setting:

const url = new URL("https://127.0.0.1:18623/api");
const pathSegments = ['process', 'read-barcode'];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("X-DICS-LICENSE-KEY", "YOUR_LICENSE_KEY_HERE");

let raw = JSON.stringify({
  settings: '{"ImageParameter":{"Name":"BestSpeed","BarcodeFormatIds_2":["BF2_POSTALCODE","BF2_DOTCODE"],"DeblurLevel":3,"ExpectedBarcodesCount":512,"LocalizationModes":[{"Mode":"LM_SCAN_DIRECTLY"}],"TextFilterModes":[{"MinImageDimension":262144,"Mode":"TFM_GENERAL_CONTOUR"}]}}',
  source: 'https://127.0.0.1:18623/api/device/scanners/jobs/dd40716d-48d1-4d32-89f7-1d53f9665d91/next-page?page=19522d0c5282',
  });

let requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. BarcodeResult[]
400 Bad Request Bad request, e.g. parameter is invalid. Error
403 Forbidden License is invalid. Error
405 Method Not Allowed Method not allowed. Error

Response Examples

200 Response

[
  {
    "BarcodeFormat": 2,
    "BarcodeFormatString": "CODE_128",
    "LocalizationResult": {
      "ResultPoints": [
        "723, 274",
        "1021, 275",
        "1021, 375",
        "723, 374"
      ],
      "accompanyingTextBytes": [],
      "angle": 0,
      "barcodeFormat": 3147775,
      "barcodeFormatString": "OneD",
      "barcodeFormatString_2": "No Barcode Format in group 2",
      "barcodeFormat_2": 0,
      "confidence": 100,
      "documentName": "{B683937D-B327-4488-A2C0-499760CB6BF0}",
      "moduleSize": 2,
      "pageNumber": 1,
      "regionName": "",
      "resultCoordinateType": 1,
      "terminatePhase": 32,
      "x1": 723,
      "x2": 1021,
      "x3": 1021,
      "x4": 723,
      "y1": 274,
      "y2": 275,
      "y3": 375,
      "y4": 374
    },
    "barcodeBytes": [
      67,
      79,
      68,
      69,
      49,
      50,
      56
    ],
    "barcodeFormat": 2,
    "barcodeFormatString": "CODE_128",
    "barcodeFormatString_2": "No Barcode Format in group 2",
    "barcodeFormat_2": 0,
    "barcodeText": "CODE128",
    "detailedResult": {
      "checkDigitBytes": [],
      "moduleSize": 2,
      "startCharsBytes": [],
      "stopCharsBytes": []
    },
    "localizationResult": {
      "ResultPoints": [
        "723, 274",
        "1021, 275",
        "1021, 375",
        "723, 374"
      ],
      "accompanyingTextBytes": [],
      "angle": 0,
      "barcodeFormat": 3147775,
      "barcodeFormatString": "OneD",
      "barcodeFormatString_2": "No Barcode Format in group 2",
      "barcodeFormat_2": 0,
      "confidence": 100,
      "documentName": "{B683937D-B327-4488-A2C0-499760CB6BF0}",
      "moduleSize": 2,
      "pageNumber": 1,
      "regionName": "",
      "resultCoordinateType": 1,
      "terminatePhase": 32,
      "x1": 723,
      "x2": 1021,
      "x3": 1021,
      "x4": 723,
      "y1": 274,
      "y2": 275,
      "y3": 375,
      "y4": 374
    },
    "results": [
      {
        "accompanyingTextBytes": [],
        "barcodeFormat": 2,
        "barcodeFormatString": "CODE_128",
        "barcodeFormatString_2": "No Barcode Format in group 2",
        "barcodeFormat_2": 0,
        "bytes": [
          67,
          79,
          68,
          69,
          49,
          50,
          56
        ],
        "clarity": -1,
        "confidence": 100,
        "deformation": 0,
        "resultType": 0
      }
    ]
  }
]

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

403 Response

{
  "code": -2800,
  "message": "The current product key is empty or invalid. Please contact the site administrator.",
  "statusCode": 403
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports POST.",
  "statusCode": 405
}

POST /process/check-blank

Create a new document process to check if a scanned page is blank.

Blank page detection is only supported on Windows.

Parameters

Name Location Type Required Restrictions Description
source body string yes Scan job URL Image source URL from the scan job, e.g. https://127.0.0.1:18623/api/device/scanners/jobs/dd40716d-48d1-4d32-89f7-1d53f9665d91/next-page?page=19522d0c5282.
settings body CheckBlankSettings no none Maximum and minimum blemish pixel height detection thresholds.

Request Example:

Check if a page from a scan job is blank:

const url = new URL("https://127.0.0.1:18623/api");
const pathSegments = ['process', `check-blank`];
url.pathname = `${url.pathname}/${pathSegments.join('/')}`;

let myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

let raw = JSON.stringify({
  settings: {
    "minBlockHeight": 20,
    "maxBlockHeight": 30
  },
  source: 'https://127.0.0.1:18623/api/device/scanners/jobs/dd40716d-48d1-4d32-89f7-1d53f9665d91/next-page?page=19522d0c5282',
  });

let requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch(url, requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

Responses

HTTP Status Code Meaning Description Data Schema
200 OK Successful operation. OperationResult
400 Bad Request Bad request, e.g. parameter is invalid. Error
405 Method Not Allowed Method not allowed. Error

Response Examples

200 Response

{
  "result": true
}

400 Response

{
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

405 Response

{
  "code": -2112,
  "message": "This endpoint only supports POST.",
  "statusCode": 405
}

Data Schema

Error

{
  "cause": {
    "code": 3,
    "message": "The system cannot find the path specified."
  },
  "code": -2113,
  "message": "The parameter is not valid.",
  "statusCode": 400
}

Attributes

Name Type Required Restrictions Description
statusCode number true HTTP status code HTTP status code
code number(int32) true none Dynamic Web TWAIN Service status code. 0 is the only successful code. All error codes are negative.
message string true none none
cause object false none If cause exists, shows the system error code and message.
» code number(int32) false none System error code.
» message string false none System error string of the code.

ScannerType

16

One or a combination of:

  • 0x10: TWAINSCANNER
  • 0x20: WIASCANNER
  • 0x40: TWAINX64SCANNER
  • 0x80: ICASCANNER
  • 0x100: SANESCANNER
  • 0x200: ESCLSCANNER
  • 0x400: WIFIDIRECTSCANNER
  • 0x800: WIATWAINSCANNER

External documentation

Attributes

Name Type Required Restrictions Description
type integer(int32) false none One or a combination of:
- 0x10: TWAINSCANNER
- 0x20: WIASCANNER
- 0x40: TWAINX64SCANNER
- 0x80: ICASCANNER
- 0x100: SANESCANNER
- 0x200: ESCLSCANNER
- 0x400: WIFIDIRECTSCANNER
- 0x800: WIATWAINSCANNER

Scanner

{
  "name": "TWAIN2 FreeImage Software Scanner",
  "type": 16,
  "device": "{\"deviceInfo\":{\"Manufacturer\":\"VFdBSU4gV29ya2luZyBHcm91cA==\",\"ProductFamily\":\"U29mdHdhcmUgU2Nhbg==\",\"ProductName\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\",\"ProtocolMajor\":2,\"ProtocolMinor\":1,\"SupportedGroups\":0,\"Version\":{\"Country\":1,\"Info\":\"Mi4xLjMgc2FtcGxlIHJlbGVhc2UgMzJiaXQ=\",\"Language\":2,\"MajorNum\":2,\"MinorNum\":1}},\"deviceType\":16,\"isSystemDefaultPrinter\":false,\"name\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\"}"
}

We also return websocket protocol info. but not list.

Attributes

Name Type Required Restrictions Description
name string true none Scanner name
type ScannerType true none one value of ScannerType
device string true none A json string of the scanner details.

CreateScanJobOptions

{
  "autoRun": false,
  "device": "{\"deviceInfo\":{\"Manufacturer\":\"VFdBSU4gV29ya2luZyBHcm91cA==\",\"ProductFamily\":\"U29mdHdhcmUgU2Nhbg==\",\"ProductName\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\",\"ProtocolMajor\":2,\"ProtocolMinor\":1,\"SupportedGroups\":0,\"Version\":{\"Country\":1,\"Info\":\"Mi4xLjMgc2FtcGxlIHJlbGVhc2UgMzJiaXQ=\",\"Language\":2,\"MajorNum\":2,\"MinorNum\":1}},\"deviceType\":16,\"isSystemDefaultPrinter\":false,\"name\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\"}",
  "name": "TWAIN2 FreeImage Software Scanner",
  "checkFeederLoaded": true,
  "config": {
    "PixelType": 1,
    "Resolution": 300,
    "IfFeederEnabled": true,
    "IfDuplexEnabled": false,
    "IfGetImageInfo": true,
    "IfGetExtImageInfo": true,
    "extendedImageInfoQueryLevel": 0,
    "IfCloseSourceAfterAcquire": true,
    "XferCount": 11
  },
  "caps": {
    "exception": "ignore",
    "capabilities": [
      {
        "capability": 4355,
        "curValue": 500
      }
    ]
  },
  "settings": "Rfj6pIMTNkCu3BfDloGItBAAAAACEAAABgAFAAEAAAAQAAAAExAAAAYABQAAAAAAEAAAAAcQAAAGAAUAAQAAABAAAAArEQAABAAFABgAAAAQAAAAHBEAAAQABQAAAAAAEAAAAAABAAAEAAUAAAAAABwAAAAUEQAACAAFAPgqAAAAAAAANCEAAAAAAAAQAAAADBEAAAQABQACAAAAEAAAAB8RAAAEAAUAAAAAABAAAAABAQAABAAFAAIAAAAQAAAAIBEAAAQABQAAAAAAEAAAACIRAAAEAAUAAwAAABAAAAAQEQAABAAFAAAAAAAQAAAAAgEAAAQABQAAAAAAEAAAABgRAAAHAAUAAABIQxAAAAAZEQAABwAFAAAASEMQAAAAIxEAAAcABQAAAABDEAAAAAMRAAAHAAUAAAAAABAAAAABEQAABwAFAAAAAAAQAAAACBEAAAcABQAAAIA/EAAAAAGAAAAGAAUAAAAAAA=="
}

Attributes

Name Type Required Restrictions Description
autoRun body boolean no Default value true - run the scan job immediately after creation. If false, the job gets created but does not run. Rather, the job status is set to pending, the scanner gets locked (no other RESTful client can use the scanner until this job completes or gets canceled), and the image source opens automatically if the scanner is a twain source. We recommend settings this to false to prevent other machines from capturing the scan job.
scannerFailureTimeout body integer(int32) no Default value 15 - communication time-out with scanner for an operation (open source, set capability/settings, acquire image)in seconds, which resets upon successful completion of the operation. The operation fails if it exceeds the time-out without a response, e.g. trying to open a disconnected scanner, a paper jam, the user not interacting with an error dialog, etc. Therefore, we recommend setting a longer time-out if the user is not physically close to the scanner.
jobTimeout body integer(int32) no Time-out for the scan job in seconds. Default value is 0 which never times out. If you create a pending job, the scanner automatically locks. You can release the scanner by deleting the job or allowing the job to time out. The timer begins once the pending job is created, and the timer stops once the job starts running. The timer resets (if set) when the job is done (completed, canceled or fault).
device body string no JSON string of scanner info in Device.device returned by GET /device/scanners.
config body object no Further scanner configurations, applied in the following order: settings -> caps -> config.
caps body object no scanner capability setting
settings body string no TWAIN-specific scanner settings, returned by /device/scanners/twain/settings. When both caps and settings exist, DWT applies settings first, then applies caps second.
checkFeederLoaded body boolean no When true, detects if the feeder is loaded on TWAIN scanners with supported drivers. Default value false. May not be reliable for unsupported drivers.

ScannerJob

{
  "jobuid": "B3701DC5-86D3-44B6-A8A1-FF0B5D43FD86",
  "status": "pending",
  "scanner": {
    "name": "TWAIN2 FreeImage Software Scanner",
    "type": 16,
    "device": "{\"deviceInfo\":{\"Manufacturer\":\"VFdBSU4gV29ya2luZyBHcm91cA==\",\"ProductFamily\":\"U29mdHdhcmUgU2Nhbg==\",\"ProductName\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\",\"ProtocolMajor\":2,\"ProtocolMinor\":1,\"SupportedGroups\":0,\"Version\":{\"Country\":1,\"Info\":\"Mi4xLjMgc2FtcGxlIHJlbGVhc2UgMzJiaXQ=\",\"Language\":2,\"MajorNum\":2,\"MinorNum\":1}},\"deviceType\":16,\"isSystemDefaultPrinter\":false,\"name\":\"VFdBSU4yIEZyZWVJbWFnZSBTb2Z0d2FyZSBTY2FubmVy\"}"
  }
}

Attributes

Name Type Required Restrictions Description
jobuid string true none none
status string true - pending: pending
- running: running
- completed: completed
- faulted: faulted
- canceled: canceled
If the job is completed, the status will be completed; If faulted, the status will be faulted, e.g. failed to open source, scanner was locked by others. Possible job status transitions:
1. pending->running->completed
2. pending->running->faulted
3. pending->running->canceled
scanner Scanner true none We also return websocket protocol info. but not list.

ScannerJobInfo

{
  "status": "pending",
  "code": "0",
  "message": "Successful"
}

Attributes

Scanner Job Information

Name Type Required Restrictions Description
status string true - pending: pending
- running: running
- completed: completed
- faulted: faulted
- canceled: canceled
Scanner job status.
code number true none error code
message string true none error message

PageInfo

{
  "uid": "190817548d70"
}

Attributes

Name Type Required Restrictions Description
uid string true none page uid

DocumentInfo

{
  "uid": "190807444d76",
  "pages": [
    {
      "uid": "190817548d70"
    }
  ]
}

Attributes

Name Type Required Restrictions Description
uid string true none document uid
pages [PageInfo] true none pages info

ServerSettingsInput

{
  "logLevel": 1
}

some settings only admin can change. can only update any of them.

Attributes

Name Type Required Restrictions Description
logLevel integer(int32) false none Log level of the DWT Service - 0 is disabled, 1 is debug + info + error, 30 is verbose.

ServerSettings

{
  "logLevel": 1
}

Currently, only return log level.

Attributes

Name Type Required Restrictions Description
logLevel integer(int32) true none Log level of the DWT Service - 0 is disabled, 1 is debug + info + error, 30 is verbose.

CreateDocumentOptions

{
  "password": ""
}

Attributes

Name Type Required Restrictions Description  
password string false none length <= 32 characters The password of the document (32 characters max).

VersionInfo

{
  "version": "20240719",
  "compatible": true
}

Attributes

Name Type Required Restrictions Description
version string false none server api version.
compatible boolean false none server is compatible with the client.

CheckBlankSettings

"settings": {
  "minBlockHeight": 20,
  "maxBlockHeight": 30
}

Attributes

Name Type Required Restrictions Description
minBlockHeight number true 0 < minBlockHeight <= maxBlockHeight Minimum blemish pixel height detection threshold.
maxBlockHeight number true minBlockHeight <= maxBlockHeight Maximum blemish pixel height detection threshold.

ScannerJobStatus

{
  "status": "running"
}

Attributes

Name Type Required Restrictions Description
status string true none scanner job status.

OperationResult

{
  "result": true
}

Attributes

Name Type Required Restrictions Description
result boolean true none is blank image or not

BarcodeResult

{
    "BarcodeFormat": 2,
    "BarcodeFormatString": "CODE_128",
    "LocalizationResult": {
      "ResultPoints": [
        "723, 274",
        "1021, 275",
        "1021, 375",
        "723, 374"
      ],
      "accompanyingTextBytes": [],
      "angle": 0,
      "barcodeFormat": 3147775,
      "barcodeFormatString": "OneD",
      "barcodeFormatString_2": "No Barcode Format in group 2",
      "barcodeFormat_2": 0,
      "confidence": 100,
      "documentName": "{B683937D-B327-4488-A2C0-499760CB6BF0}",
      "moduleSize": 2,
      "pageNumber": 1,
      "regionName": "",
      "resultCoordinateType": 1,
      "terminatePhase": 32,
      "x1": 723,
      "x2": 1021,
      "x3": 1021,
      "x4": 723,
      "y1": 274,
      "y2": 275,
      "y3": 375,
      "y4": 374
    },
    "barcodeBytes": [
      67,
      79,
      68,
      69,
      49,
      50,
      56
    ],
    "barcodeFormat": 2,
    "barcodeFormatString": "CODE_128",
    "barcodeFormatString_2": "No Barcode Format in group 2",
    "barcodeFormat_2": 0,
    "barcodeText": "CODE128",
    "detailedResult": {
      "checkDigitBytes": [],
      "moduleSize": 2,
      "startCharsBytes": [],
      "stopCharsBytes": []
    },
    "localizationResult": {
      "ResultPoints": [
        "723, 274",
        "1021, 275",
        "1021, 375",
        "723, 374"
      ],
      "accompanyingTextBytes": [],
      "angle": 0,
      "barcodeFormat": 3147775,
      "barcodeFormatString": "OneD",
      "barcodeFormatString_2": "No Barcode Format in group 2",
      "barcodeFormat_2": 0,
      "confidence": 100,
      "documentName": "{B683937D-B327-4488-A2C0-499760CB6BF0}",
      "moduleSize": 2,
      "pageNumber": 1,
      "regionName": "",
      "resultCoordinateType": 1,
      "terminatePhase": 32,
      "x1": 723,
      "x2": 1021,
      "x3": 1021,
      "x4": 723,
      "y1": 274,
      "y2": 275,
      "y3": 375,
      "y4": 374
    },
    "results": [
      {
        "accompanyingTextBytes": [],
        "barcodeFormat": 2,
        "barcodeFormatString": "CODE_128",
        "barcodeFormatString_2": "No Barcode Format in group 2",
        "barcodeFormat_2": 0,
        "bytes": [
          67,
          79,
          68,
          69,
          49,
          50,
          56
        ],
        "clarity": -1,
        "confidence": 100,
        "deformation": 0,
        "resultType": 0
      }
    ]
  }