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.
Endpoint | Method | Description |
---|---|---|
/server |
GET |
Get server settings |
/server |
PATCH |
Update specified server settings |
/server/version |
GET |
Get server API version |
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 |
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 |
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:
- completes successfully,
- hangs indefinitely,
- times out once it hits the
jobTimeout
value if set, - 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
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
}
]
}