Scan Barcode API

How it works

1. The source file is passed to the converter and API scans for supported barcode types.
2. Each detected barcode is decoded.
3. Results are returned as a JSON array, where each object represents one detected barcode.

How to perform the conversion

You can call the converter via a standard HTTP POST request. Below is an example using curl:

curl -X POST "https://v2.convertapi.com/convert/barcode/to/data" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "File=@/path/to/your/file.pdf" \
  -F "StoreFile=true"

Output JSON

The barcode data is returned as a JSON file in the API response.

After conversion, the API returns a standard ConvertAPI response containing a Files array.
Each file entry includes a Url where you can download the generated JSON file.

API response example

{
  "ConversionCost": 1,
  "Files": [
    {
      "FileName": "Barcodes.json",
      "FileExt": "json",
      "FileSize": 612,
      "FileId": "abc123examplefileid",
      "Url": "https://v2.convertapi.com/d/jesmx8nz3ax34psd88ch6jjhuwwvfj12/Barcodes.json"
    }
  ]
}

Downloaded JSON file content

The downloaded JSON file contains the actual barcode detection results:

[
  {
    "Text": "decoded value",
    "Format": "Code128",
    "RawBytes": "base64-encoded bytes",
    "Metadata": {
      "SymbologyIdentifier": "]C0",
      "Orientation": "0"
    },
    "Points": [
      { "X": 96, "Y": 75 },
      { "X": 492, "Y": 75 }
    ]
  }
]

If multiple barcodes are found, the array contains multiple objects.

Field reference

Text - The decoded human-readable barcode value.

This is usually the main field your application will consume. For example, it may contain a product code, tracking number, identifier, or payload embedded in the barcode.

Format - The detected barcode format.

Possible formats: Code128, Code39, QRCode, DataMatrix, Ean13, Ean8, Pdf417, Aztec, Codabar, UpcA, UpcE, Itf14, UspsMail

Use this field when your workflow needs to validate or branch by barcode type.

RawBytes - Base64-encoded raw bytes returned by the decoder.

This field is useful when you need access to the original decoded byte payload, not just the text representation. It is not guaranteed to be present for every barcode type.

Metadata - Additional decoder-provided information about the detected barcode.

The exact fields may vary by barcode format and by what information is available for the detected symbol.

Common metadata fields include:

• SymbologyIdentifier - A standardized identifier describing the recognized symbology and data interpretation mode.
• Orientation - The detected rotation of the barcode, typically expressed in degrees as a string such as "0", "90", "180", or "270".
• ErrorCorrectionLevel - Returned for some 2D formats. Indicates the error-correction setting or strength reported for the barcode.
• ErrorsCorrected - Returned for some 2D formats. Indicates how many decoding errors were corrected during recognition.

Because metadata is format-dependent, client code should treat this object as extensible and avoid assuming that every field is always present.

Points - Coordinates describing where the barcode was detected in the source image or page.

Each point contains:

• X - horizontal coordinate
• Y - vertical coordinate

The number of points depends on the barcode type:

• 1D barcodes usually return 2 points
• 2D barcodes usually return 4 points

For 1D barcodes, the points typically describe the detected scan line or horizontal extent.
For 2D barcodes, the points usually describe the detected corners or bounding shape.

Coordinates are relative to the processed image or PDF page.

Example: Code128

[
  {
    "Text": "12345678",
    "Format": "Code128",
    "RawBytes": "aQwiOE4vag==",
    "Metadata": {
      "SymbologyIdentifier": "]C0",
      "Orientation": "0"
    },
    "Points": [
      { "X": 96, "Y": 75 },
      { "X": 492, "Y": 75 }
    ]
  }
]

Explanation

• Text contains the decoded barcode value: 12345678
• Format confirms that the detected symbology is Code128
• RawBytes contains the decoded payload in Base64 form
• Metadata.SymbologyIdentifier provides the symbology identifier
• Metadata.Orientation shows that the barcode was read without rotation
• Points contains 2 coordinates, which is typical for a 1D barcode

Example: Aztec

[
  {
    "Text": "12345678",
    "Format": "Aztec",
    "RawBytes": "8aKzxNfA",
    "Metadata": {
      "ErrorCorrectionLevel": "58",
      "ErrorsCorrected": "0",
      "SymbologyIdentifier": "]z0",
      "Orientation": "0"
    },
    "Points": [
      { "X": 554.5, "Y": 44.5 },
      { "X": 554.5, "Y": 554.5 },
      { "X": 44.5, "Y": 554.5 },
      { "X": 44.5, "Y": 44.5 }
    ]
  }
]

Explanation

• Format is Aztec, which is a 2D barcode format
• RawBytes is included because binary payload information is available
• ErrorCorrectionLevel and ErrorsCorrected provide additional decoding details
• Points contains 4 coordinates, which is typical for a 2D barcode and helps describe the detected shape in the page or image

Additional examples

Code39

[
  {
    "Text": "12345678",
    "Format": "Code39",
    "Metadata": {
      "SymbologyIdentifier": "]A0",
      "Orientation": "0"
    },
    "Points": [
      { "X": 66, "Y": 75 },
      { "X": 534, "Y": 75 }
    ]
  }
]

EAN-8

[
  {
    "Text": "12345670",
    "Format": "Ean8",
    "Metadata": {
      "SymbologyIdentifier": "]E4",
      "Orientation": "0"
    },
    "Points": [
      { "X": 75.5, "Y": 75 },
      { "X": 523.5, "Y": 75 }
    ]
  }
]

Codabar

[
  {
    "Text": "12345678",
    "Format": "Codabar",
    "Metadata": {
      "SymbologyIdentifier": "]F0",
      "Orientation": "0"
    },
    "Points": [
      { "X": 47, "Y": 75 },
      { "X": 552, "Y": 75 }
    ]
  }
]

Practical parsing notes

When integrating the JSON result, it is best to assume that:

• the result may contain zero, one, or many barcode objects
• RawBytes may be missing
• Metadata fields are format-specific
• point count differs between 1D and 2D barcodes
• numeric values in Points may be integers or decimals

A robust parser should therefore:

• iterate through the result array
• read Text and Format first
• treat Metadata as optional and extensible
• handle both 2-point and 4-point Points arrays

Summary

The Scan Barcode API returns a clean, developer-friendly JSON structure:

• one array item per detected barcode
• decoded value in Text
• barcode type in Format
• optional binary payload in RawBytes
• additional details in Metadata
• detected location in Points

This makes the converter suitable for document automation, inventory workflows, validation pipelines, and barcode extraction from scanned or photographed files.