Barcode Recognition

Detects and decodes 1D and 2D barcodes in an image that you provide.

The Barcode Recognition API detects barcodes from an image. For each recognized barcode, it returns the type, the decoded barcode value, and the coordinates of the corners of a box that surrounds the barcode.

Quick Start

The Barcode Recognition API accepts an image as input, as either a file, a URL, or a Haven OnDemand reference (created by adding the file by using the Store Object API.

/1/api/[async|sync]/recognizebarcodes/v1?file= or reference= or url=

For a list of file formats that you can use for images, see Supported Media Formats.

The following curl request posts the productimage.jpg file to the API:

curl -X POST -F "file=@productimage.jpg"

The API recognizes any barcodes in the image, and returns the type of the barcode, the text value of the barcode, and the location of the barcode in the image. It provides the location as the coordinates of the upper left corner of a box that surrounds the barcode, and the width and height of the box.

For EAN-13 and UPC-A type barcodes, the API also returns the GS1 country code of the barcode as additional information.

  "barcode": [
      "text": "5000108030539",
      "barcode_type": "ean-13",
      "left": 295,
      "top": 634,
      "width": 515,
      "height": 263,
      "additional_information": {
        "country": "United Kingdom"

Barcode recognition is most reliable for approximately horizontally or vertically aligned barcodes (up to 20° rotation), although in some cases detection works for all alignments up to 45°. The image must also be high contrast, and preferably two-tone (black and white).

The Barcode Recognition API recognizes barcodes with the following formats:

  • EAN-13 (includes ISBN)
    Note: The EAN-13 barcode type is a superset of the UPC-A type, so the API returns the EAN type, rather than the UPC value. To find the UPC value, remove the leading 0 from the EAN value.
  • EAN-8
  • EAN-2 (includes ISBN-2)
  • EAN-5 (includes ISBN-5)
  • Codabar
  • Code-128
  • Code-39
  • Code-93
  • Datalogic 2/5
  • Data Matrix
  • IATA 2/5
  • Industrial 2/5
  • Matrix 2/5
  • Patch Code (or Patch)
  • PDF417
  • UCC/EAN-128 (or GS1-128)
  • UPC-A
  • UPC-E
  • QR Code

For more information about barcode formats, refer to


This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.

This API accepts the following parameters:

Name Type Description
binary The image file to process.
string A Haven OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding document is passed to the API.
string A publicly accessible HTTP URL from which the image can be retrieved.
Name Type Description
enum Information about the barcode orientation in the images that you are submitting. Default value: any.
array<enum> The type of barcode you are trying to recognize. Default value: [all1d,qr].
Enumeration Types

This API's parameters use the enumerations described below:

Information about the barcode orientation in the images that you are submitting.
upright Upright
Your barcodes are always in an upright orientation.
any Any
Your barcodes can be in any orientation.
The type of barcode you are trying to recognize.
all All
All supported barcode types.
all1d All supported 1D types
All 1-Dimensional barcode types.
all2d All supported 2D types
All 2-Dimensional barcode types.
codabar Codabar (1D)
code-128 Code-128 (1D)
code-39 Code-39 (1D)
code-93 Code-93 (1D)
datalogic 2/5 Datalogic 2/5 (1D)
data matrix Data Matrix (2D)
ean-128 EAN-128 (1D)
ean-13 EAN-13 (1D)
ean-2 EAN-2 (1D)
ean-5 EAN-5 (1D)
ean-8 EAN-8 (1D)
iata 2/5 IATA 2/5 (1D)
industrial 2/5 Industrial 2/5 (1D)
matrix 2/5 Matrix 2/5 (1D)
patch code Patch Code (1D)
pdf417 PDF417 (2D)
qr QR Code (2D)
ucc UCC (1D)
upc-a UPC-A (1D)
upc-e UPC-E (1D)

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

This is an abstract definition of the response that describes each of the properties that might be returned.
Barcode Recognition Response {
barcode ( array[Barcode] ) Details of a recognized barcode in the image.
page_count ( integer , optional) The total number of pages in the document.
Barcode Recognition Response:Barcode {
additional_information ( Additional_information , optional)
barcode_type ( enum<Barcode_type> ) The type of barcode recognized.
height ( integer ) The height of the barcode in the image.
left ( integer ) The position of the left edge of the barcode in the image.
text ( string ) The decoded barcode value.
top ( integer ) The position of the top edge of the barcode in the image.
width ( integer ) The width of the barcode in the image.
page_num ( integer , optional) The page in the document that the barcode belongs to.
enum<Barcode Recognition Response:Barcode:Barcode_type> {
'codabar' See
'code-128' See
'code-39' See
'code-93' See
'datalogic 2/5'
'data matrix'
'ean-128/ucc' See
'ean-13' See
'ean-2' See http://
'ean-5' See
'ean-8' See
'iata 2/5'
'industrial 2/5' See
'matrix 2/5' See
'patch code'
'pdf417' See
'qr' See
'ucc/ean-128' See
'upc-a' See
'upc-e' See
Barcode Recognition Response:Barcode:Additional_information {
country ( string , optional) The GS1 country code of the barcode (EAN-13 and UPC-A barcodes only).
Model Schema
This is a JSON schema that describes the syntax of the response. See for a complete reference.
    "properties": {
        "barcode": {
            "items": {
                "properties": {
                    "additional_information": {
                        "properties": {
                            "country": {
                                "type": "string"
                        "type": "object"
                    "barcode_type": {
                        "enum": [
                            "datalogic 2/5",
                            "data matrix",
                            "iata 2/5",
                            "industrial 2/5",
                            "matrix 2/5",
                            "patch code",
                    "height": {
                        "type": "integer"
                    "left": {
                        "type": "integer"
                    "text": {
                        "type": "string"
                    "top": {
                        "type": "integer"
                    "width": {
                        "type": "integer"
                    "page_num": {
                        "type": "integer"
                "required": [
                "type": "object"
            "type": "array"
        "page_count": {
            "type": "integer"
    "required": [
    "type": "object"
See this API for yourself - select one of our examples below.
Select file Change Remove
Name Type Value
(Default: [all1d,qr])

Async – Response An error occurred making the API request
Response Code:
Response Body

Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

Make this call with curl

Note: The API key used in this call will expire after 24 hours. You can create a persistent API key for use in your application on the Account API Keys page

If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.