Introduction

The Barcode Scanner REST API allows your application to take a source document as input and produce a list of scanned barcodes as output.

Available URLs

Getting Started

The following topic contains an explanation of how to get started using the Barcode Scanner REST API and includes sample code for interacting with the service in C#.

• Try The Barcode Scanner REST API

POST /barcode/api/v1/scanners

Creates and starts a new barcode scanner process.

A barcode scanner represents a process that runs on the server and creates a list of scanned barcodes.

The server process to scan barcodes is started by this request, but a response is sent before the process is complete. Use the GET https://api.accusoft.com/barcode/api/v1/scanners/{processId} URL below to get the state and results of an in-progress or completed barcode scanner process.

A new barcode list containing the scanned barcodes will be created.

NOTES:

1. The barcode scanner supports the following input file types:

   • TIFF
   • JPEG
   • PNG

2. The barcode scanner works for single-page files. If the input file contains more than one page, it will scan the first page and ignore the rest.

Request

Request Headers

Request Body

JSON object conforming to the following:

• input
  • source (Object) Required. An object that defines the source document.
    • fileId (String) Required. The ID of the WorkFile which represents the source document that will be scanned. See the work file API topic to find out how to upload a WorkFile.
  • additionalReadingPass (Boolean) Determines if an additional processing pass of a scaled (reduced) version of the original image will be performed (scale factor equal to 0.5). After analyzing both these images, results from the pass that yields a higher confidence value would be reported. This step is strictly an extra analysis step which increases response time. It can be used for barcode images with repetitive noise artifacts around the bars which cause normal recognition pass to misread. The default is false
  • barcodeTypes (Array) A list of the barcode types to recognize. Barcode types not included in this array will be ignored.
    • "all1D" - Indicates All 1D barcode types.
    • "all2D" - Indicates all 2D barcode types. These types are "qrCodeBarcode", "microQRCodeBarcode", - "pdf417Barcode", - "microPdf417Barcode", and "dataMatrixBarcode".
    • "allPostal" - Indicates all Postal barcode types. These types are "australianPost4StateBarcode", "intelligentMailBarcode", "planetBarcode", "postNetBarcode", and "royalPost4StateBarcode".
    • "add2Barcode" - Indicates an Add 2 barcode type.
    • "add5Barcode" - Indicates an Add 5 barcode type.
    • "australianPost4StateBarcode" - Australian Post 4 State barcode
    • "aztecBarcode" - Aztec barcode
    • "bcdMatrixBarcode" - Indicates a BCD Matrix barcode type.
    • "codabarBarcode" - Indicates a Codabar barcode type.
    • "code128Barcode" - Indicates a Code 128 barcode type.
    • "code32Barcode" - Indicates a Code 32 barcode type.
    • "code39Barcode" - Indicates a Code 39 barcode type.
    • "code39ExtendedBarcode" - Indicates a Code 39 Extended barcode type.
    • "code93Barcode" - Indicates a Code 93 barcode type.
    • "code93ExtendedBarcode" - Indicates a Code 93 Extended barcode type.
    • "dataLogic2Of5Barcode" - Indicates a DataLogic 2 of 5 barcode type.
    • "dataMatrixBarcode" - Indicates a DataMatrix barcode type.
    • "ean128Barcode" - Indicates an EAN-128 barcode type.
    • "ean13Barcode" - Indicates an EAN-13 barcode. This also supports a JAN barcode which is an EAN-13 with country code 49.
    • "ean8Barcode" - Indicates an EAN-8 barcode type.
    • "gs1DataBarBarcode" - GS1 DataBar barcode
    • "iata2Of5Barcode" - Indicates an IATA 2 of 5 barcode type.
    • "industry2Of5Barcode" - Indicates an Industry 2 of 5 barcode type.
    • "intelligentMailBarcode" - United States Postal IntelligentMail 4 State barcode
    • "interleaved2Of5Barcode" - Indicates an Interleaved 2 of 5 barcode type.
    • "invert2Of5Barcode" - Indicates an Inverted 2 of 5 barcode type.
    • "matrix2Of5Barcode" - Indicates a Matrix 2 of 5 barcode type.
    • "microPdf417Barcode" - MicroPDF417 barcode
    • "microQRCodeBarcode" - MicroQR Code barcode
    • "patchCodeBarcode" - Indicates a Patch Code. Note: If you want to search for Patch Codes, you must specify only this one type. If any other type is also selected, the barcode scanner will scan for that other type instead.
    • "pdf417Barcode" - Indicates a PDF417 barcode type.
    • "planetBarcode" - Planet barcode
    • "postNetBarcode" - Indicates a PostNet barcode type.
    • "qrCodeBarcode" - QR Code barcode
    • "royalPost4StateBarcode" - Royal Post 4 State barcode
    • "unknownBarcode" - (Default) Indicates an unknown 1D barcode. Looks for all 1D barcode types only. The 1D barcode set includes all types, except Patch Code, PostNet, GS1 DataBar, IntelligentMail, Royal Post Mail 4-State, Australian Post 4-State, QR Code, PDF417, Aztec and DataMatrix. Note: If this type is combined with any other type, the barcode scanner will scan for the other type instead.
    • "upcABarcode" - Indicates a UPC-A barcode type.
    • "upcEBarcode" - Indicates a UPC-E barcode type.
    • "upu4StateBarcode" - UPU 4-State barcode
  • appendCheckSum (Boolean) Determines if checksum values will be appended for barcode types that require a checksum. This property does not have any effect for barcode types which do not have a checksum or for which the checksum is optional. Note: The UPC and EAN codes always append the checksum character to the barcode results. This is done regardless of this property's value. The default is false
  • code39StartStopPatternsAreMandatory (Boolean) Determines whether only regular (barcode has both start and stop patterns) barcodes are recognized. When this property is set to false then both regular and barcodes without start/stop patterns are recognized. This is relevant for Code39 and Code39 Extended barcode symbologies. The default is true
  • returnPossibleBarcodes (Boolean) Determines if the barcode scanner returns candidate barcodes which could not be decoded in the results list. For 1D barcodes, any unsolved regions of interest in the barcode result list have a barcodeType of "unknown" and the barcodeValue property will be NULL. For the following 2D barcodes types including DataMatrix, PDF417, Aztec, QRcode, PostNet, Intelligent Mail, Australian Post and Royal Post 4, the currently selected barcodeType is returned as the candidate region type. The default is false
  • royalMailVariableLength (Boolean) Specifies whether or not to decode Royal Mail barcodes of any length. If set to false, only Royal Mail barcodes matching the lengths in the RM4SCC specification will be decoded. The default is false
  • scanDistance (Integer between 1 and 10 inclusive) Determines the scan distance in pixels between line sweeps when searching for 1D barcodes. Reducing this value can help in finding barcodes which are short relative to their height. This value affects the run time of the barcode search. Smaller values will require more processing of the image. The default is 5
  • orientation (Enumeration) Specifies the orientation of the barcodes to analyze during recognition. The barcode recognition engine is capable of detecting barcodes in an image without any prior knowledge of the barcode orientation. However, you can speed up the recognition process by specifying a barcode orientation.
    • "horizontal" - Barcodes with only a horizontal orientation will be searched.
    • "horizontalVertical" - (Default) Search for barcodes in horizontal and vertical direction.
    • "horizontalVerticalDiagonal" - Barcodes will be searched for in Horizontal, Vertical and 45 degrees. This will increase processing time.
    • "vertical" - Barcodes with only a vertical orientation will be searched.
• minSecondsAvailable (Integer) The minimum number of seconds this barcode scanner status will remain available via a GET request. The actual lifetime may be longer. The default lifetime is defined by the processIds.lifetime [central configuration] parameter.

Successful Response

Response body

JSON object with the following properties:

• input (Object) A copy of the request body input object.
• processId (String) The id of the new barcode scanner process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the barcode scanner will be deleted.
• state (String) The current state of the barcode scanner process running on the server. The response will always be "processing".

Error Responses

Example

Request

POST /barcode/api/v1/scanners
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    }
  },
  "minSecondsAvailable": 60
}

Response

HTTP 200 OK
Content-Type: application/json
{
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-07T13:24:35.395Z",
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    }
  },
  "state": "processing"
}

GET /barcode/api/v1/scanners/{processId}

Gets the state and result of an existing barcode scanner process created by POST /barcode/api/v1/scanners.

Requests can be sent to this URL repeatedly while the state is "processing".

When the state is "complete", the response will include the list of scanned barcodes.

If the barcode scanner process encountered an error, the state property will be "error" and the errorCode property will contain an error code string.

Request

Parameters

Response body

JSON object with the following properties:

• input (Object) A copy of the POST /barcode/api/v1/scanners request body input object we accepted to create the barcode scanner process.
• processId (String) The id of the barcode scanner process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the barcode scanner will be deleted.
• state (String) The current state of the barcode scanner process running on the server. The following values are allowed:
  • "processing" * The barcode scanner is in progress.
  • "complete" * The barcode scanner is completed.
  • "error" * The barcode scanner returns an error.
• errorCode (String) An error code string if a problem occurred during the barcode scanner process. It is only present when state is "error".
• output (Object) Describes the scanned barcodes. Only present when state is "complete".
  • barcodes[] (Array of Objects) Objects describing scanned barcodes. Each item will contain:
    • area (Object) The bounding rectangular area of the recognized barcode.
      • x (Integer) The distance, in pixels, from the left edge of the image to the left edge of the bounding rectangular area of the recognized barcode.
      • y (Integer) The distance, in pixels, from the top edge of the image to the top edge of the bounding rectangular area of the recognized barcode.
      • width (Integer) The width, in pixels, of the bounding rectangular area of the recognized barcode.
      • height (Integer) The height, in pixels, of the bounding rectangular area of the recognized barcode.
    • barcodeDataAsBytes (Base64 String) The barcode data value as an array of bytes in the form of a base*64 string. An application can use this array, plus a specific encoding, to decode the bytes to a string.
    • barcodeType (Enumeration) The type of the recognized barcode.
    • barcodeValue (String) The value of the recognized barcode. This property represents values using ANSI encoding. If the barcodes being recognized are encoding binary data, use the barcodeDataAsBytes property to return the result value instead.
    • confidence (Integer) The confidence of the recognized barcode. Barcodes are assumed to have a 100 percent confidence from which points are deducted. Confidence reporting is based on several factors (all of these modifications of the confidence can be combined):
      • Barcodes that require the use of check digits that have not produced the anticipated checksum value will cause a reduced confidence. Invalid checksums will have a reduction of at least 50.
      • Barcodes that are recognized but that also include errors will cause a reduction in confidence. These could be barcodes that were recovered because of the checksum. The confidence of these barcodes is reduced by as much as 30.
    • numberOfCheckSumChars (Integer) The number of characters in the recognized checksum. If a checksum does not exist, or the checksum evaluated incorrectly, this property will return 0.
    • point1 (Object) The top*left point of the recognized barcode. Point properties 1 through 4 locate the corner points of linear 1D barcodes. With any rotation of the barcode on the image, the point value assigned to the corners rotates with the barcode. No matter what the rotation is, the point properties always identify the same corner point of the barcode.
      • x (Integer) The distance, in pixels, from the left edge of the image to the point.
      • y (Integer) The distance, in pixels, from the top edge of the image to the point.
    • point2 (Object) The top*right point of the recognized barcode. Point properties 1 through 4 locate the corner points of linear 1D barcodes. With any rotation of the barcode on the image, the point value assigned to the corners rotates with the barcode. No matter what the rotation is, the point properties always identify the same corner point of the barcode.
      • x (Integer) The distance, in pixels, from the left edge of the image to the point.
      • y (Integer) The distance, in pixels, from the top edge of the image to the point.
    • point3 (Object) The bottom*right point of the recognized barcode. Point properties 1 through 4 locate the corner points of linear 1D barcodes. With any rotation of the barcode on the image, the point value assigned to the corners rotates with the barcode. No matter what the rotation is, the point properties always identify the same corner point of the barcode.
      • x (Integer) The distance, in pixels, from the left edge of the image to the point.
      • y (Integer) The distance, in pixels, from the top edge of the image to the point.
    • point4 (Object) The bottom*left point of the recognized barcode. Point properties 1 through 4 locate the corner points of linear 1D barcodes. With any rotation of the barcode on the image, the point value assigned to the corners rotates with the barcode. No matter what the rotation is, the point properties always identify the same corner point of the barcode.
      • x (Integer) The distance, in pixels, from the left edge of the image to the point.
      • y (Integer) The distance, in pixels, from the top edge of the image to the point.
    • skew (Integer) The angle of skew, in degrees, for the scanned barcode. 0 degrees indicates horizontal.
    • validCheckSum (Boolean) Indicates that the checksum for a scanned barcode is valid. For barcodes that do not have a checksum, this value will always be false. For barcodes that have error correction, this value will always be true.

Error Responses and JSON Error Codes

Example

Request

GET /barcode/api/v1/scanners/iFhSZRvrz2vtFjcTSi9Qlg

Successful Response

When the barcode scanner process completes with no errors:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-07T13:24:35.395Z",
  "state": "complete",
  "output": {
    "barcodes":
    [
      {
        "area": 
        {
            "x": 496,
            "y": 81,
            "width": 646,
            "height": 99
        },        
        "barcodeDataAsBytes": "NDQxMjMxMjM0NTYxMjM0NTY3KiogVU5MSUNFTlNFRCBhY2N1c29mdC5jb20A",
        "barcodeType": "intelligentMail",
        "barcodeValue": "44123123456123456789"       
        "confidence": 100,
        "numberCheckSumChars": 0,
        "point1": 
        {
            "x": 496,
            "y": 81
        },
        "point2": 
        {
            "x": 496,
            "y": 81
        },
        "point3": 
        {
            "x": 496,
            "y": 81
        },
        "point4": 
        {
            "x": 496,
            "y": 81
        },
        "skew": 0,
        "validCheckSum": true           
      }
    ]
  }
}

Error responses

Response when a barcode scanner process does not exist for the given processId:

HTTP 404
Content-Type: application/json
{
  "errorCode": "ResourceNotFound",
  "errorDetails": {
    "in": "url",
    "at": "processId",
  },
}

Response when a barcode scanner process did exist for the given processId, but has passed its expiration time:

HTTP 410
Content-Type: application/json
{
  "errorCode": "ResourceExpired",
  "errorDetails": {
    "in": "url",
    "at": "processId",
  },
}

Response when source document is a file format that is not supported by the barcode scanner:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "UnsupportedFileFormat",
  "errorDetails": {
    "in": "process",
    "at": "input.source.fileId"
  },
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}