POST /v1/barcode/read/from/url

Attributes

Attributes are case-sensitive and should be inside JSON for POST request. for example: { "url": "https://example.com/file1.pdf" }
AttributeTypeRequiredDefaultDescription
urlstringYes-URL to the source file url attribute
callbackstringNo-The callback URL (or Webhook) used to receive the POST data. see Webhooks & Callbacks. This is only applicable when async is set to true.
httpusernamestringNo-HTTP auth user name if required to access source URL.
httppasswordstringNo-HTTP auth password if required to access source URL.
pagesstringNoall pagesSpecify page indices as comma-separated values or ranges to process (e.g. “0, 1, 2-” or “1, 2, 3-7”). The first-page index is 0. Use ”!” before a number for inverted page numbers (e.g. “!0” for the last page). If not specified, the default configuration processes all pages. The input must be in string format.
asyncbooleanNofalseSet async to true for long processes to run in the background, API will then return a jobId which you can use with the Background Job Check endpoint. Also see Webhooks & Callbacks
typestringYesQRCodeSet the barcode type to be used. See available barcode types in the Supported Barcode Types
typesstringNo-Detects checkboxes, radiobuttons, vertical and horizontal lines, and general segments (all content types) on scanned documents using the barcode reader engine. Comma-separated list of object types to decode, must be in a string format.
profilesobjectNo-See Profiles for more information.
    DataEncryptionAlgorithmstringNo-Controls the encryption algorithm used for data encryption. See User-Controlled Encryption for more information. The available algorithms are: AES128, AES192, AES256.
    DataEncryptionKeystringNo-Controls the encryption key used for data encryption. See User-Controlled Encryption for more information.
    DataEncryptionIVstringNo-Controls the encryption IV used for data encryption. See User-Controlled Encryption for more information.
    DataDecryptionAlgorithmstringNo-Controls the decryption algorithm used for data decryption. See User-Controlled Encryption for more information. The available algorithms are: AES128, AES192, AES256.
    DataDecryptionKeystringNo-Controls the decryption key used for data decryption. See User-Controlled Encryption for more information.
    DataDecryptionIVstringNo-Controls the decryption IV used for data decryption. See User-Controlled Encryption for more information.

Query parameters

No query parameters accepted.

Responses

ParameterTypeDescription
barcodesarray[object]List of barcodes found in the document
pageCountintegerNumber of pages in the PDF document.
errorbooleanIndicates whether an error occurred (false means success)
statusstringStatus code of the request (200, 404, 500, etc.). For more information, see Response Codes.
creditsintegerNumber of credits consumed by the request
remainingCreditsintegerNumber of credits remaining in the account
durationintegerTime taken for the operation in milliseconds

types

Detects checkboxes, radiobuttons, vertical and horizontal lines, and general segments (all content types) on scanned documents using the barcode reader engine.

Comma-separated list of object types to decode, must be in a string format.

Visual Element Detection Modes

  • Checkbox: Locates check boxes.
  • Segment: Locates and selects objects on a page (general selection).
  • UnderlinedField: Detects fillable fields (typically, underlined spaces, i.e. fields to fill in a form).
  • Rectangle: Detects rectangles, including checkboxes. Also returns the value as 1 if a checkmark or a filled rectangle was detected.
  • Oval: Detects rounded or oval marks (typically, a radiobutton). Returns value of 1 if filled out radiobutton was detected.
  • HorizontalLine: Detects horizontal lines.
  • VerticalLine: Detects vertical lines.

Normal Example

Example Payload

To see the request size limits, please refer to the Request Size Limits.
{
  "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-to-html/sample.pdf",
  "types": "Checkbox,UnderlinedField",
  "async": false
}

Example Response

To see the main response codes, please refer to the Response Codes page.
{
  "barcodes": [
    {
      "Value": "abcdef123456",
      "RawData": "",
      "Type": 14,
      "Rect": "{X=448,Y=23,Width=106,Height=112}",
      "Page": 0,
      "File": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/barcode-reader/sample.pdf",
      "Confidence": 1,
      "Metadata": "",
      "TypeName": "QRCode"
    },
    {
      "Value": "test123",
      "RawData": "",
      "Type": 2,
      "Rect": "{X=111,Y=60,Width=255,Height=37}",
      "Page": 0,
      "File": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/barcode-reader/sample.pdf",
      "Confidence": 0.90625155,
      "Metadata": "",
      "TypeName": "Code128"
    },
    {
      "Value": "123456",
      "RawData": "",
      "Type": 4,
      "Rect": "{X=111,Y=129,Width=306,Height=37}",
      "Page": 0,
      "File": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/barcode-reader/sample.pdf",
      "Confidence": 0.7710818,
      "Metadata": "",
      "TypeName": "Code39"
    },
    {
      "Value": "<FNC1>0112345678901231",
      "RawData": "",
      "Type": 2,
      "Rect": "{X=111,Y=198,Width=305,Height=37}",
      "Page": 0,
      "File": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/barcode-reader/sample.pdf",
      "Confidence": 0.9156459,
      "Metadata": "",
      "TypeName": "Code128"
    },
    {
      "Value": "12345670",
      "RawData": [
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        0
      ],
      "Type": 5,
      "Rect": "{X=111,Y=267,Width=182,Height=0}",
      "Page": 0,
      "File": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/barcode-reader/sample.pdf",
      "Confidence": 1,
      "Metadata": "",
      "TypeName": "I2of5"
    },
    {
      "Value": "1234567890128",
      "RawData": "",
      "Type": 6,
      "Rect": "{X=102,Y=336,Width=71,Height=72}",
      "Page": 0,
      "File": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/barcode-reader/sample.pdf",
      "Confidence": 0.895925164,
      "Metadata": "",
      "TypeName": "EAN13"
    }
  ],
  "pageCount": 1,
  "error": false,
  "status": 200,
  "remainingCredits": 99826192,
  "credits": 35
}

Example CURL

curl --location --request POST 'https://api.pdf.co/v1/barcode/read/from/url' \
--header 'x-api-key: *******************' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/barcode-reader/sample.pdf",
"types": "QRCode,Code128,Code39,Interleaved2of5,EAN13",
"pages": "0",
"async": false
}'

Optical Marks Reader

Our barcode reader engine can also find the following marks and objects on scanned documents:

  • Checkboxes
  • Radioboxes
  • Vertical and horizontal lines
  • General segments (basically, all content types on the page).

Example Payload

To see the request size limits, please refer to the Request Size Limits.
{
  "url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/barcode-reader/sample.pdf",
  "types": "QRCode,Code128,Code39,Interleaved2of5,EAN13",
  "pages": "0",
  "async": false
}

Example Response

To see the main response codes, please refer to the Response Codes page.
{
  "barcodes": [
    {
      "Value": "box",
      "RawData": "",
      "Type": 53,
      "Rect": "{X=298,Y=437,Width=132,Height=6}",
      "Page": 0,
      "File": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-to-html/sample.pdf",
      "Confidence": 1,
      "Metadata": "",
      "TypeName": "UnderlinedField"
    }
  ],
  "pageCount": 1,
  "error": false,
  "status": 200,
  "duration": 860,
  "remainingCredits": 98725528,
  "credits": 35
}

Example CURL

curl --location --request POST 'https://api.pdf.co/v1/barcode/read/from/url' \
--header 'x-api-key: *******************' \
--header 'Content-Type: application/json' \
--data-raw '{
"url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-to-html/sample.pdf",
"types": "Checkbox,UnderlinedField",
"async": false
}'

Code Samples

var https = require("https");

// The authentication key (API Key).
// Get your own by registering at https://app.pdf.co
const API_KEY = "***********************************";


// Direct URL of source file to search barcodes in.
const SourceFileUrl = "https://bytescout-com.s3.amazonaws.com/files/demo-files/cloud-api/barcode-reader/sample.pdf";
// Comma-separated list of barcode types to search.
// See valid barcode types in the documentation https://developer.pdf.co
const BarcodeTypes = "Code128,Code39,Interleaved2of5,EAN13";
// Comma-separated list of page indices (or ranges) to process. Leave empty for all pages. Example: '0,2-5,7-'.
const Pages = "";

// Prepare request to `Barcode Reader` API endpoint
var queryPath = `/v1/barcode/read/from/url`;

// JSON payload for api request
var jsonPayload = JSON.stringify({
    types: BarcodeTypes,
    pages: Pages,
    url: SourceFileUrl
});

var reqOptions = {
    host: "api.pdf.co",
    method: "POST",
    path: queryPath,
    headers: {
        "x-api-key": API_KEY,
        "Content-Type": "application/json",
        "Content-Length": Buffer.byteLength(jsonPayload, 'utf8')
    }
};

// Send request
var postRequest = https.request(reqOptions, (response) => {
    response.on("data", (d) => {
        // Parse JSON response
        var data = JSON.parse(d);

        if (data.error == false) {
            // Display found barcodes in console
            data.barcodes.forEach((element) => {
                console.log("Found barcode:");
                console.log("  Type: " + element.TypeName);
                console.log("  Value: " + element.Value);
                console.log("  Document Page Index: " + element.Page);
                console.log("  Rectangle: " + element.Rect);
                console.log("  Confidence: " + element.Confidence);
                console.log("");
            }, this);
        }
        else {
            // Service reported error
            console.log(data.message);
        }
    });
}).on("error", (e) => {
    // Request error
    console.error(e);
});

// Write request data
postRequest.write(jsonPayload);
postRequest.end();