PDF.co API v.1.00

• PDF.co Web API (Application Programming Interface)
  • Key Benefits
  • How to use API with large files and with 100+ pages documents
  • Asynchronious mode and background jobs: step by step
  • How to Upload Files
  • Source Code Samples
  • Known Issues
  • Free Customer Support

PDF.co API Benefits

• Security: API runs on the secure Amazon AWS infrastructure. All data transfers are encrypted by SSL/TLS encryption.
• Asynchronous mode is supported so you can process large files and documents with hundreds of pages in the cloud.
• Battle tested by thousands of production user. Our engines are tested in production by thousands of enterprise user.
• Credits based system. For evert page/image processed credits are reduced on your account. You get monthly amount of credits based on your subscription, also you may always purchase additional credits. Separate methods like uploading, background job also consumes credits. You may always see how may credits are left using remainingCredits property in the returned result or by exploring your API logs

• On-Premise API Server and SDKs are available

• Not a developer? Zapier, UiPath, Integromat and hundreds of other integrations are available

Status Errors Returned by PDF.co Web API

! Don’t forget to set x-api-key url param or http header param (preferred) to API key, get yours here

How to use API with large files and with 100+ pages documents

We’ve designed special async that is available for almost all endpioints. With async mode you can process large files and documents with hundreds of pages.

• Default timeout for all API calls without async mode is no more than 25 seconds. If your call to API (for example, if you run text recognition on 100+ pages scanned document) takes more time then you should use async mode by setting async to true.
• Enable async mode by setting async input parameter to true. This will tell API method to reate background job and immediately return unique id of this new background job in jobId property in the output along with the final url. Use this url to access output file (if any) once the job is finished.
• Now use Check status of that new background job using /job/check. Wait until it returns status as success

Asynchronious mode and background jobs: step by step

1. Request a temporary URL for upload using /file/upload/get-presigned-url. This will return presignedUrl to be used for uploading and url that must be used to access uploaded file.
2. Upload your file using PUT to this presignedUrl generated on the previous step. Once finished, your file can be accessed using the url link from step 1
3. Call API method wuth input set in url param. Set async param to true so API method will return immediately and will send you output URL (or set of URLs) along with jobId immediately. jobId is the unique identificator of the background job that will be running on the server.
4. Now check status of this background job using /job/check API method with jobId param. It will return execution status.
5. Once /job/check returns status param as success you may use the previously generated output URL (or set of URLs) to download generated data.

Source Code Samples

We have hundreds of ready to copy Explore Source Code Samples on Github available for Javascript, Node.js, PHP, Java, C# and Visual Basic NET.

Known Issues

• PHP language: if you are getting SSL certificate error: unable to get local issuer certificate error then please check this solution on Stackoverflow

Free Tech Support

Our team of engineers is happy to help with the integration, coding of proof of concept projects and any other questions. To contact us please:

• Submit a Ticket (recommended)
• or send email to pdfco@bytescout.zendesk.com

Indices

• Background Jobs

  • /job/check

• Barcode Generator

  • /barcode/generate

• Barcode Reader

  • /barcode/read/from/url

• Document Parser

  • /pdf/documentparser (output as CSV)
  • /pdf/documentparser (output as JSON)
  • /pdf/documentparser (output as JSON, custom template code)
  • /pdf/documentparser (output as XML)
  • /pdf/documentparser/results
  • /pdf/documentparser/results
  • /pdf/documentparser/results/:id
  • /pdf/documentparser/templates
  • /pdf/documentparser/templates/:id

• Files Upload

  • /file/delete
  • /file/hash
  • /file/upload (Uploading small file)
  • /file/upload/base64 (Upload small file as Base64)
  • /file/upload/get-presigned-url (GET generate secure URL for upload)
  • /file/upload/url (Upload file from URL)
  • /file/upload/url (Upload from URL)
  • PUT presignedUrl –formdata file=..

• PDF Add Text and Images to PDF

  • /pdf/edit/add
  • /pdf/edit/add (with simplified parameters)

• PDF Create Fillable PDF Forms

  • /pdf/edit/add

• PDF Delete Pages

  • /pdf/edit/delete-pages

• PDF Fill PDF Forms

  • /pdf/edit/add
  • /pdf/edit/add (with simplified params)

• PDF Forms Info Reader

  • /pdf/info/fields

• PDF Info Reader

  • /pdf/info

• PDF Merge

  • /pdf/merge
  • /pdf/merge2 (supports documents, spreadsheets, images as sources)

• PDF Optimize

  • /pdf/optimize

• PDF Password And Security

  • /pdf/security/add
  • /pdf/security/remove

• PDF Search Text

  • /pdf/find

• PDF Search and Delete Text from PDF

  • /pdf/edit/delete-text (multiple replacements)
  • /pdf/edit/delete-text (single replacement)

• PDF Search and Replace Text

  • /pdf/edit/replace-text (mutliple replacements)
  • /pdf/edit/replace-text (single replacement)

• PDF Search and Replace Text with Image

  • /pdf/edit/replace-text-with-image

• PDF Split

  • /pdf/split

• PDF To CSV

  • /pdf/convert/to/csv

• PDF To JSON

  • /pdf/convert/to/json

• PDF To TEXT

  • /pdf/convert/to/text

• PDF To XLS

  • /pdf/convert/to/xls

• PDF To XLSX

  • /pdf/convert/to/xls

• PDF To XML

  • /pdf/convert/to/xml

• PDF from CSV (CSV to PDF)

  • /pdf/convert/from/csv

• PDF from Doc, DocX, RTF, TXT, XPS (Document to PDF)

  • /pdf/convert/from/doc

• PDF from Email

  • /email/decode
  • /email/extract-attachments
  • /pdf/convert/from/email
  • /pdf/convert/from/email with Orientation and paper Size

• PDF from HTML (HTML to PDF)

  • /pdf/convert/from/html
  • /pdf/convert/from/html (with custom profiles and custom js to disable links)

• PDF from HTML template (Mustache or HandleBars style)

  • /pdf/convert/from/html (using simple inline HTML template)
  • /pdf/convert/from/url (invoice template 1)
  • /pdf/convert/from/url (invoice template 2)
  • /pdf/convert/from/url (invoice template 3)

• PDF from Images (JPG to PDF and PNG to PDF)

  • /pdf/convert/from/image

• PDF from URL (URL to PDF)

  • /pdf/convert/from/url

• PDF from XLS or CSV

  • /xls/convert/to/pdf

• PDF to HTML

  • /pdf/convert/to/html

• PDF to JPG

  • /pdf/convert/to/jpg

• PDF to PNG

  • /pdf/convert/to/png

• PDF to TIFF

  • /pdf/convert/to/tiff

• PDF to Text Searchable PDF

  • /pdf/makesearchable

• XLS / XLSX to CSV

  • /xls/convert/to/csv

• XLS/XLSX to HTML

  • /xls/convert/to/html

• XLS/XLSX to JSON

  • /xls/convert/to/json

• XLS/XLSX to TXT

  • /xls/convert/to/txt

• XLS/XLSX to XML

  • /xls/convert/to/xml

Background Jobs

Checks status of background job that was previously created with PDF.co API.

1. /job/check

• jobId required. Id of background that was started asynchronously. Must be a String. To start new async background job, you should set async to true for API methods.
• force optional. Set to true to forcely check the status of the background job. Intended to be used with really long and heavy background jobs only.

Returns JSON with status of the background job.

Available status values:

• working background job is currently in work or does not exist.
• success background job was successfully finished.
• failed background job failed for some reason (see message for more details).
• aborted background job was aborted.
• unknown unknown background job id. Available only when force is set to true for input request.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/job/check

Headers:

Body:

{
    "jobid": "12345"
}

More example Requests/Responses:

I. Example Request: /job/check

Headers:

Body:

{
    "jobid": "12345"
}

I. Example Response: /job/check

{
    "status": "working",
    "remainingCredits": 60227
}

Status Code: 200

Barcode Generator

Generate high quality barcode images. Supports QR Code, Datamatrix, Code 39, Code 128, PDF417 and many other barcode types.

1. /barcode/generate

• type optional. Sets barcode type. QRCode is default. Available values: Code128, Code39, Postnet, UPCA, EAN8, ISBN, Codabar, I2of5, Code93, EAN13, JAN13, Bookland, UPCE, PDF417, PDF417Truncated, DataMatrix, QRCode, Aztec, Planet, EAN128, GS1_128, USPSSackLabel, USPSTrayLabel, DeutschePostIdentcode, DeutschePostLeitcode, Numly, PZN, OpticalProduct, SwissPostParcel, RoyalMail, DutchKix, SingaporePostalCode, EAN2, EAN5, EAN14, MacroPDF417, MicroPDF417, GS1_DataMatrix, Telepen, IntelligentMail, GS1_DataBar_Omnidirectional, GS1_DataBar_Truncated, GS1_DataBar_Stacked, GS1_DataBar_Stacked_Omnidirectional, GS1_DataBar_Limited, GS1_DataBar_Expanded, GS1_DataBar_Expanded_Stacked, MaxiCode, Plessey, MSI, ITF14, GTIN12, GTIN8, GTIN13, GTIN14.

• inline. optional. Set to true to generate datauri url instead of file.

• decorationImage optional. works for QR Code only. Set this to the image that you want to be inserted logo inside QR Code barcode. To use your file please upload it first to the temporary storage, see Upload and Manage Files section below to learn how to do it.

• profiles optional. Must be a String. You can set additional and extra options using this parameter that allows you to set custom configuration. See profiles samples for examples.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/barcode/generate

Headers:

Body:

{
    "name": "barcode.png",
    "value": "abcdef123456",
    "type": "QRCode",
    "inline": false,
    "decorationImage": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/barcode-generator/logo.png"
}

More example Requests/Responses:

I. Example Request: /barcode/generate

Headers:

Body:

{
    "name": "barcode.png",
    "value": "abcdef123456",
    "type": "QRCode",
    "inline": false,
    "decorationImage": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/barcode-generator/logo.png"
}

I. Example Response: /barcode/generate

{
    "url": "https://pdf-temp-files.s3.amazonaws.com/9a87556a8b9e4f4eae60843e697250d4/barcode.png",
    "error": false,
    "status": 200,
    "name": "barcode.png",
    "remainingCredits": 60631
}

Status Code: 200

Barcode Reader

Read barcodes from images and PDF. Can read all popular barcode types from QR Code and Code 128, EAN to Datamatrix, PDF417, GS1 and many other barcodes.

1. /barcode/read/from/url

• url required. URL to the source file. Supports links from Google Drive, Dropbox and from built-in PDF.co files storage. For uploading files via API please check Files Upload section.

• type. optional. Comma-separated list of barcode types to decode. Barcode types supported: AustralianPostCode, Aztec, CircularI2of5, Codabar, CodablockF, Code128, Code16K, Code39, Code39Extended, Code39Mod43, Code39Mod43Extended, Code93, DataMatrix, EAN13, EAN2, EAN5, EAN8, GS1, GS1DataBarExpanded, GS1DataBarExpandedStacked, GS1DataBarLimited, GS1DataBarOmnidirectional, GS1DataBarStacked, GTIN12, GTIN13, GTIN14, GTIN8, IntelligentMail, Interleaved2of5, ITF14, MaxiCode, MICR, MicroPDF, MSI, PatchCode, PDF417, Pharmacode, PostNet, PZN, QRCode, RoyalMail, RoyalMailKIX, Trioptic, UPCA, UPCE, UPU. Must be a String.

• pages. optional. Comma-separated list of page indices (or ranges) to process. IMPORTANT: the very first page starts at 0 (zero). To set a range use the dash -, for example: 0,2-5,7-. To set a range from index to the last page use range like this: 2- (from page #3 as the index starts at zero and till the of the document). For ALL pages just leave this param empty. Example: 0,2-5,7- means first page, then 3rd page to 6th page, and then the range from 8th (index = 7) page till the end of the document. Must be a String.

• profiles optional. Must be a String. You can set additional and extra options using this parameter that allows you to set custom configuration. See profiles samples for examples.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/barcode/read/from/url

Headers:

Body:

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/barcode-reader/sample.pdf",
    "types": "Code128,Code39,Interleaved2of5,EAN13",
    "pages": "0",
    "encrypt": false,
    "async": false
}

More example Requests/Responses:

I. Example Request: /barcode/read/from/url

Headers:

Body:

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/barcode-reader/sample.pdf",
    "types": "Code128,Code39,Interleaved2of5,EAN13",
    "pages": "0",
    "encrypt": false,
    "async": false
}

I. Example Response: /barcode/read/from/url

{
    "barcodes": [
        {
            "Value": "test123",
            "RawData": "",
            "Type": 2,
            "Rect": "{X=111,Y=60,Width=255,Height=37}",
            "Page": 0,
            "File": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/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://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/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://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/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://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/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://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/barcode-reader/sample.pdf",
            "Confidence": 0.895925164,
            "Metadata": "",
            "TypeName": "EAN13"
        }
    ],
    "pageCount": 1,
    "error": false,
    "status": 200,
    "remainingCredits": 60661
}

Status Code: 200

Document Parser

Document Parser automatically extracts fields, tables, values from invoices, statements, orders and other PDF and scanned documents.

Built-in templates:

• Invoices (currently, English language only) can be parsed by the built-in template 1 (set the templateId param to 1).

Helper tools:

• Document Parser Template Editor (or check a standalone version here)
• Manual Template Coding Guide

Some Sample Templates

Simple templates (extracting data from fixed coordinates) can be easily created with Document Parser template editor

Complex templates are also supported. You can edit them using the editor and also can edit manually.

Sample PDF document: PDF document with tables and multiple pages

Below is the template that demonstrates parsing of multi-page table using only regular expressions for the table start, end, and rows. If regular expression cannot be used for every table row (for example, if the table contains empty cells), try the second template below (MultiPageTable-template2) showcasing another approach.

MultipageTable-template1.json:

{
  "templateVersion": 3,
  "templatePriority": 0,
  "sourceId": "Multipage Table Test",
  "detectionRules": {
    "keywords": []
  },
  "fields": {
    "total": {
      "type": "regex",
      "expression": "TOTAL {{DECIMAL}}",
      "dataType": "decimal"
    }
  },
  "tables": [
    {
      "name": "table1",
      "start": {
        "expression": "Item\\s+Description\\s+Price\\s+Qty\\s+Extended Price"
      },
      "end": {
        "expression": "TOTAL\\s+\\d+\\.\\d\\d"
      },
      "row": {
        "expression": "^\\s*(?<itemNo>\\d+)\\s+(?<description>.+?)\\s+(?<price>\\d+\\.\\d\\d)\\s+(?<qty>\\d+)\\s+(?<extPrice>\\d+\\.\\d\\d)"
      },
      "columns": [
        {
          "name": "itemNo",
          "type": "integer"
        },
        {
          "name": "description",
          "type": "string"
        },
        {
          "name": "price",
          "type": "decimal"
        },
        {
          "name": "qty",
          "type": "integer"
        },
        {
          "name": "extPrice",
          "type": "decimal"
        }
      ],
      "multipage": true
    }
  ]
}

NOTE: put this template code into the template param as string. You can also just add this template into your templates and reference to it using templateId param.

1. /pdf/documentparser (output as CSV)

Description: Gets data from documents using a data extraction template. With this API method you may extract data from custom areas, by search, form fields, tables, multiple pages and more!

Additional tools and guides:

• Document Parser Template Editor

• Template Manual Coding Guide

• url required. URL to the source file. Supports links from Google Drive, Dropbox and from built-in PDF.co files storage. For uploading files via API please check Files Upload section.
• templateId. required. Sets Id of document parser template to be used. View and manage your templates at https://app.pdf.co/document-parser
• template. optional. You can pass code of document parser template to be used directly.
• inline. optional. Set to true to return results inside the response. Otherwise endpoint will return a link to output file generated.
• outputFormat. optional. Default is JSON. You can override default output format to CSV or XML to generate CSV or XML output accordingly.
• storeResult. optional. Set to true if you want to store results generated in PDF.co. You can view stored data extraction results at https://app.pdf.co/document-parser
• password optional. Password of PDF file. Must be a String
• async optional. Runs processing asynchronously. Returns Use JobId that you may use with /job/check to check state of the processing (possible states: working, failed, aborted and success). Must be one of: true, false.
• encrypt optional. Enable encryption for output file. Must be one of: true, false.
• name optional. File name for generated output. Must be a String.
• profiles optional. Must be a String. You can set additional and extra options using this parameter that allows you to set custom configuration. See profiles samples for examples.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/pdf/documentparser

Headers:

Body:

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/document-parser/sample-invoice.pdf",
    "templateId": "1",
    "outputFormat": "CSV",
    "generateCsvHeaders": true,

    "async": false,
    "encrypt": "false",
    "inline": "true",
    "password": "",
    "storeResult": false

}

More example Requests/Responses:

I. Example Request: /pdf/documentparser (output as CSV)

Headers:

Body:

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/document-parser/sample-invoice.pdf",
    "templateId": "1",
    "outputFormat": "CSV",
    "generateCsvHeaders": true,

    "async": false,
    "encrypt": "false",
    "inline": "true",
    "password": ""
}

I. Example Response: /pdf/documentparser (output as CSV)

{
    "body": "companyName,companyName2,invoiceId,dateIssued,dateDue,bankAccount,total,subTotal,tax,tableNames,tables\r\n\"Amazon Web Services, Inc\",\"Amazon Web Services, Inc\",123456789,2018-04-03T00:00:00,2018-04-03T00:00:00,123456789012,6.58,,1.01,table,\r\n\r\n",
    "pageCount": 1,
    "error": false,
    "status": 200,
    "name": "sample-invoice.csv",
    "remainingCredits": 60804
}

Status Code: 200

2. /pdf/documentparser (output as JSON)

Description: Gets data from documents using a data extraction template. With this API method you may extract data from custom areas, by search, form fields, tables, multiple pages and more!

Additional tools and guides:

• Document Parser Template Editor
• Template Manual Coding Guide

Parameters

• url required. URL to the source file. Supports links from Google Drive, Dropbox and from built-in PDF.co files storage. For uploading files via API please check Files Upload section.
• templateId. required. Sets Id of document parser template to be used. View and manage your templates at https://app.pdf.co/document-parser
• template. optional. You can pass code of document parser template to be used directly.
• inline. optional. Set to true to return results inside the response. Otherwise endpoint will return a link to output file generated.
• outputFormat. optional. Default is JSON. You can override default output format to CSV or XML to generate CSV or XML output accordingly.
• storeResult. optional. Set to true if you want to store results generated in PDF.co. You can view stored data extraction results at https://app.pdf.co/document-parser
• password optional. Password of PDF file. Must be a String
• async optional. Runs processing asynchronously. Returns Use JobId that you may use with /job/check to check state of the processing (possible states: working, failed, aborted and success). Must be one of: true, false.
• encrypt optional. Enable encryption for output file. Must be one of: true, false.
• name optional. File name for generated output. Must be a String.
• profiles optional. Must be a String. You can set additional and extra options using this parameter that allows you to set custom configuration. See profiles samples for examples.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/pdf/documentparser

Headers:

Body:

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/document-parser/sample-invoice.pdf",
    "outputFormat": "JSON",
    "templateId": "1",
    "async": false,
    "encrypt": "false",
    "inline": "true",
    "password": "",
    "profiles": "",
    "storeResult": false
}

More example Requests/Responses:

I. Example Request: /pdf/documentparser (output as JSON)

Headers:

Body:

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/document-parser/sample-invoice.pdf",
    "outputFormat": "JSON",
    "templateId": "1",
    "async": false,
    "encrypt": "false",
    "inline": "true",
    "password": "",
    "profiles": ""    
}

I. Example Response: /pdf/documentparser (output as JSON)

{
    "body": {
        "objects": [
            {
                "name": "companyName",
                "objectType": "field",
                "value": "Amazon Web Services, Inc",
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "companyName2",
                "objectType": "field",
                "value": "Amazon Web Services, Inc",
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "invoiceId",
                "objectType": "field",
                "value": "123456789",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "dateIssued",
                "objectType": "field",
                "value": "2018-04-03T00:00:00",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "dateDue",
                "objectType": "field",
                "value": "2018-04-03T00:00:00",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "bankAccount",
                "objectType": "field",
                "value": "123456789012",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "total",
                "objectType": "field",
                "value": 6.58,
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "subTotal",
                "objectType": "field",
                "value": ""
            },
            {
                "name": "tax",
                "objectType": "field",
                "value": 1.01,
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "objectType": "table",
                "name": "table",
                "rows": []
            }
        ],
        "templateName": "Generic Invoice [en]",
        "templateVersion": "4",
        "timestamp": "2020-08-21T19:23:31"
    },
    "pageCount": 1,
    "error": false,
    "status": 200,
    "name": "sample-invoice.json",
    "remainingCredits": 60803
}

Status Code: 200

3. /pdf/documentparser (output as JSON, custom template code)

Description: Parses and gets data from documents using previously prepared custom data extraction template. With this API method you may extract data from custom areas, by search, form fields, tables, multiple pages and more!

Template tools and guides:

• Document Parser Template Editor
• Template Manual Coding Guide

Parameters

• url required. URL to the source file. Supports links from Google Drive, Dropbox and from built-in PDF.co files storage. For uploading files via API please check Files Upload section.
• templateId. required. Sets Id of document parser template to be used. View and manage your templates at https://app.pdf.co/document-parser
• template. optional. You can pass code of document parser template to be used directly.
• inline. optional. Set to true to return results inside the response. Otherwise endpoint will return a link to output file generated.
• outputFormat. optional. Default is JSON. You can override default output format to CSV or XML to generate CSV or XML output accordingly.
• storeResult. optional. Set to true if you want to store results generated in PDF.co. You can view stored data extraction results at https://app.pdf.co/document-parser
• password optional. Password of PDF file. Must be a String
• async optional. Runs processing asynchronously. Returns Use JobId that you may use with /job/check to check state of the processing (possible states: working, failed, aborted and success). Must be one of: true, false.
• encrypt optional. Enable encryption for output file. Must be one of: true, false.
• name optional. File name for generated output. Must be a String.
• profiles optional. Must be a String. You can set additional and extra options using this parameter that allows you to set custom configuration. See profiles samples for examples.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/pdf/documentparser

Headers:

Body:

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/document-parser/MultiPageTable.pdf",
    "template": "{\r\n  \"templateVersion\": 3,\r\n  \"templatePriority\": 0,\r\n  \"sourceId\": \"Multipage Table Test\",\r\n  \"detectionRules\": {\r\n    \"keywords\": [\r\n      \"Sample document with multi-page table\"\r\n    ]\r\n  },\r\n  \"fields\": {\r\n    \"total\": {\r\n      \"type\": \"regex\",\r\n      \"expression\": \"TOTAL {{DECIMAL}}\",\r\n      \"dataType\": \"decimal\"\r\n    }\r\n  },\r\n  \"tables\": [\r\n    {\r\n      \"name\": \"table1\",\r\n      \"start\": {\r\n        \"expression\": \"Item\\\\s+Description\\\\s+Price\\\\s+Qty\\\\s+Extended Price\"\r\n      },\r\n      \"end\": {\r\n        \"expression\": \"TOTAL\\\\s+\\\\d+\\\\.\\\\d\\\\d\"\r\n      },\r\n      \"row\": {\r\n        \"expression\": \"^\\\\s*(?<itemNo>\\\\d+)\\\\s+(?<description>.+?)\\\\s+(?<price>\\\\d+\\\\.\\\\d\\\\d)\\\\s+(?<qty>\\\\d+)\\\\s+(?<extPrice>\\\\d+\\\\.\\\\d\\\\d)\"\r\n      },\r\n      \"columns\": [\r\n        {\r\n          \"name\": \"itemNo\",\r\n          \"type\": \"integer\"\r\n        },\r\n        {\r\n          \"name\": \"description\",\r\n          \"type\": \"string\"\r\n        },\r\n        {\r\n          \"name\": \"price\",\r\n          \"type\": \"decimal\"\r\n        },\r\n        {\r\n          \"name\": \"qty\",\r\n          \"type\": \"integer\"\r\n        },\r\n        {\r\n          \"name\": \"extPrice\",\r\n          \"type\": \"decimal\"\r\n        }\r\n      ],\r\n      \"multipage\": true\r\n    }\r\n  ]\r\n}",
    "outputFormat": "JSON",
    "async": false,
    "encrypt": "false",
    "inline": "true",
    "profiles": "",
    "password": "",
    "storeResult": false
}

More example Requests/Responses:

I. Example Request: POST /pdf/documentparser

Headers:

Body:

I. Example Response: POST /pdf/documentparser

{
    "body": {
        "objects": [
            {
                "name": "companyName",
                "objectType": "field",
                "value": "Amazon Web Services, Inc",
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "companyName2",
                "objectType": "field",
                "value": "Amazon Web Services, Inc",
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "invoiceId",
                "objectType": "field",
                "value": "123456789",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "dateIssued",
                "objectType": "field",
                "value": "2018-04-03T00:00:00",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "dateDue",
                "objectType": "field",
                "value": "2018-04-03T00:00:00",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "total",
                "objectType": "field",
                "value": 6.58,
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "subTotal",
                "objectType": "field",
                "value": ""
            },
            {
                "name": "tax",
                "objectType": "field",
                "value": 1.01,
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "objectType": "table",
                "name": "table",
                "rows": []
            }
        ],
        "templateName": "Generic Invoice [en]",
        "templateVersion": "4",
        "timestamp": "2020-07-16T22:04:25"
    },
    "pageCount": 1,
    "error": false,
    "status": 200,
    "name": "sample-invoice.json",
    "remainingCredits": 77731
}

Status Code: 200

4. /pdf/documentparser (output as XML)

Description: Gets data from documents using a data extraction template. With this API method you may extract data from custom areas, by search, form fields, tables, multiple pages and more!

Additional tools and guides:

• Document Parser Template Editor
• Template Manual Coding Guide

Parameters

• url required. URL to the source file. Supports links from Google Drive, Dropbox and from built-in PDF.co files storage. For uploading files via API please check Files Upload section.
• templateId. required. Sets Id of document parser template to be used. View and manage your templates at https://app.pdf.co/document-parser
• template. optional. You can pass code of document parser template to be used directly.
• inline. optional. Set to true to return results inside the response. Otherwise endpoint will return a link to output file generated.
• outputFormat. optional. Default is JSON. You can override default output format to CSV or XML to generate CSV or XML output accordingly.
• storeResult. optional. Set to true if you want to store results generated in PDF.co. You can view stored data extraction results at https://app.pdf.co/document-parser
• password optional. Password of PDF file. Must be a String
• async optional. Runs processing asynchronously. Returns Use JobId that you may use with /job/check to check state of the processing (possible states: working, failed, aborted and success). Must be one of: true, false.
• encrypt optional. Enable encryption for output file. Must be one of: true, false.
• name optional. File name for generated output. Must be a String.
• profiles optional. Must be a String. You can set additional and extra options using this parameter that allows you to set custom configuration. See profiles samples for examples.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/pdf/documentparser

Headers:

Body:

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/document-parser/sample-invoice.pdf",
    "outputFormat": "JSON",
    "templateId": "1",
    "async": false,
    "encrypt": "false",
    "inline": "true",
    "password": "",
    "profiles": "",
    "storeResult": false
}

More example Requests/Responses:

I. Example Request: /pdf/documentparser (output as JSON)

Headers:

Body:

{
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/document-parser/sample-invoice.pdf",
    "outputFormat": "JSON",
    "templateId": "1",
    "async": false,
    "encrypt": "false",
    "inline": "true",
    "password": "",
    "profiles": ""    
}

I. Example Response: /pdf/documentparser (output as JSON)

{
    "body": {
        "objects": [
            {
                "name": "companyName",
                "objectType": "field",
                "value": "Amazon Web Services, Inc",
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "companyName2",
                "objectType": "field",
                "value": "Amazon Web Services, Inc",
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "invoiceId",
                "objectType": "field",
                "value": "123456789",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "dateIssued",
                "objectType": "field",
                "value": "2018-04-03T00:00:00",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "dateDue",
                "objectType": "field",
                "value": "2018-04-03T00:00:00",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "bankAccount",
                "objectType": "field",
                "value": "123456789012",
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "total",
                "objectType": "field",
                "value": 6.58,
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "name": "subTotal",
                "objectType": "field",
                "value": ""
            },
            {
                "name": "tax",
                "objectType": "field",
                "value": 1.01,
                "pageIndex": 0,
                "rectangle": [
                    0,
                    0,
                    0,
                    0
                ]
            },
            {
                "objectType": "table",
                "name": "table",
                "rows": []
            }
        ],
        "templateName": "Generic Invoice [en]",
        "templateVersion": "4",
        "timestamp": "2020-08-21T19:23:31"
    },
    "pageCount": 1,
    "error": false,
    "status": 200,
    "name": "sample-invoice.json",
    "remainingCredits": 60803
}

Status Code: 200

5. /pdf/documentparser/results

Return all document parser results for this user. Please use GET request.

Endpoint:

Method: GET
Type: 
URL: https://api.pdf.co/v1/pdf/documentparser/results

Headers:

Query params:

More example Requests/Responses:

I. Example Request: JSON pdf/documentparser/results

Headers:

Query:

I. Example Response: JSON pdf/documentparser/results

{
    "results": [
        {
            "id": 74,
            "templateId": 40,
            "body": {
                "fields": {
                    "date": {
                        "value": ""
                    },
                    "amount": {
                        "value": "2",
                        "pageIndex": 0
                    }
                },
                "sourceId": null,
                "templateId": null,
                "templateVersion": "3"
            },
            "createdAt": "2020-03-23T11:17:30.152Z",
            "filename": "EINPresswire-Report-512260784-bytescout-announces-release-of-its-data-extraction-tools-for-on-cloud-deployments.pdf"
        }
    ],
    "remainingCredits": 94220
}

Status Code: 200

6. /pdf/documentparser/results

Description Create document parser result for this user. Please use POST request.

Input Parameters

Status Errors

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/pdf/documentparser/results

Headers:

Body:

{
    "fileUrl": "https://github.com/bytescout/ByteScout-SDK-SourceCode/raw/master/Document%20Parser%20SDK/DigitalOcean.pdf",
    "templateId": 48,
    "formatType": "CSV",
    "result": "companyName,companyName2,invoiceId,dateIssued,dateDue,total,subTotal,tax\r\n,,,,,450.00,,\r\n\r\n"
}

7. /pdf/documentparser/results/:id

DELETE document parser result with given id. Please use DELETE request.

Endpoint:

Method: DELETE
Type: 
URL: https://api.pdf.co/v1/pdf/documentparser/results/:id

Headers:

URL variables:

8. /pdf/documentparser/templates

Return all data extraction templates for document parser for this user. Please use GET request.

Endpoint:

Method: GET
Type: 
URL: https://api.pdf.co/v1/pdf/documentparser/templates

Headers:

More example Requests/Responses:

I. Example Request: pdf/documentparser/templates

Headers:

I. Example Response: pdf/documentparser/templates

{
    "templates": [
        {
            "id": 40,
            "type": "user",
            "title": "Untitled",
            "description": "Untitled"
        },
        {
            "id": 1,
            "type": "system",
            "title": "Invoice Parser",
            "description": "Parses invoices and extracts invoice number, company name, due date, amount, tax"
        }
    ],
    "remainingCredits": 94229
}

Status Code: 0

9. /pdf/documentparser/templates/:id

Returns detailed information for document parser template by template’s id. Please use GET request.

Endpoint:

Method: GET
Type: RAW
URL: https://api.pdf.co/v1/pdf/documentparser/templates/:id

Headers:

URL variables:

Files Upload

Files Storage

You can upload files as temporary files into PDF.co. Temporary files are stored for 1 hour by default and then auto removed.

To store files permanently (pdf templates, images you want to re-use) please use PDF.co built-in files storage at https://app.pdf.co/files instead.

You can also use 3rd party cloud services:

• Dropbox: you can use public link to a file from Dropbox
• Google Drive: you can use link to a file that was shared as anyone with a link
• Google Docs/Sheets/Slides: you can use a link to a document in Google Docs that was shared as anyone with a link
• Any other cloud service that can store a file and provide a link to uploaded file.

IMPORTANT NOTE FOR GOOGLE DRIVE/DOCS users: free Google Drive/Docs limits number of requests to their files. If you use link to file or document from Google Drive or Google Drive then make sure you have no more than 5-10 requests per minute. Otherwise Google Drive returns no file or error page.

Temporary Files Upload

You can upload temporary files up to 2GB in size. Please note that to process these files you should use async=true mode with data extraction and tools endpoints along with /job/check to check status of background jobs you create.

Steps to Upload File:

1) First, call /file/upload/get-presigned-url. It will generate link for uploading (presignedUrl) and final link (url) 2) Now send your file to the presignedUrl link using PUT method within next 30 minutes. 3) Oncce finished, use url to access the file you have just uploaded.

Note: all uploaded files are considered to be temporary files and are automatically permanently removed after 1 hour.

Status Errors

Example: Uploading a Temporary File

Sample Request:

! Don’t forget to set x-api-key url param or http header param (preferred) to API key, get yours here

GET
https://api.pdf.co/v1/file/upload/get-presigned-url?name=test.pdf&encrypt=true

200
{
    "presignedUrl": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/28e191b14f3a4f43b16fcef1d53d191e/test.pdf?X-Amz-Expires=900&....",
    "url": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/28e191b14f3a4f43b16fcef1d53d191e/test.pdf?X-Amz-Expires=....",
    "error": false,
    "status": 200,
    "name": "test.pdf",
    "remainingCredits": 93574
}

PUT
https://pdf-temp-files.s3-us-west-2.amazonaws.com/28e191b14f3a4f43b16fcef1d53d191e/test.pdf?X-Amz-Expires=900&....
--form 'file=@/path/to/file'

200
{
}

Now you can access your file using link from "url" param to from the first step.

1. /file/delete

Description: Deletes temp file (that was uploaded by you or generated by API)

IMPORTANT: All temp files are autoremoved after 1 hour. You may use /file/delete methods to explicitely force remove temp files once you don’t need them.

Parameters

• url required. URL of previously uploaded temporary file or output file that was generated by API method.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/file/delete

Headers:

Body:

{
    "file": "https://pdf-temp-files.s3.amazonaws.com/b5c1e67d98ab438292ff1fea0c7cdc9d/sample.pdf"
}

More example Requests/Responses:

I. Example Request: /file/delete

Headers:

Body:

I. Example Response: /file/delete

{
  "error": false,
  "status": 200,
  "remainingCredits": 9999986
}

Status Code: 200

II. Example Request: POST /file/delete

Headers:

Body:

II. Example Response: POST /file/delete

{
    "error": false,
    "status": 200,
    "remainingCredits": 77778
}

Status Code: 200

2. /file/hash

Description: Calculate and return MD5 hash of file by url. Commonly used to control if source document has been changed or not because every little change will cause hash string to differ as well. GET or POST request.

Parameters

• url required. URL to the source file. Supports links from Google Drive, Dropbox and from built-in PDF.co files storage. For uploading files via API please check Files Upload section.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/file/hash

Headers:

Body:

{
    "url": "https://bytescout-com.s3.amazonaws.com/files/demo-files/cloud-api/pdf-split/sample.pdf"
}

More example Requests/Responses:

I. Example Request: /file/hash

Headers:

Body:

{
    "url": "https://bytescout-com.s3.amazonaws.com/files/demo-files/cloud-api/pdf-split/sample.pdf"
}

I. Example Response: /file/hash

{
    "hash": "d942e5becdcb0386598cce15e9e56deb1ca9d893b8578a88eca4a62f02c4000b",
    "remainingCredits": 98143
}

Status Code: 200

3. /file/upload (Uploading small file)

Description: Uploads a small (up to 100KB) local file as a temporary file in PDF.co storage. Note: temporary files are automatically permanently removed after 1 hour.

Status Errors

Example

Sample Request:

! Don’t forget to set x-api-key url param or http header param (preferred) to API key, get yours here

Endpoint:

Method: POST
Type: POST params, JSON or FORMDATA
URL: https://api.pdf.co/v1/file/upload

Headers:

Body:

More example Requests/Responses:

I. Example Request: /file/upload/url

Headers:

Body:

I. Example Response: /file/upload/url

{
    "url": "https://pdf-temp-files.s3.amazonaws.com/1a4a92ac805c41c28ef75a24e0f35ba5/sample.pdf",
    "error": false,
    "status": 200,
    "name": "sample.pdf",
    "remainingCredits": 98145
}

Status Code: 200

II. Example Request: POST Upload small file: /file/upload

Headers:

Body:

II. Example Response: POST Upload small file: /file/upload

{
    "url": "https://pdf-temp-files.s3.amazonaws.com/28b6041bcfe34c469ed44f15f0594d5f/logo.dat",
    "error": false,
    "status": 200,
    "name": "logo",
    "remainingCredits": 77772
}

Status Code: 200

4. /file/upload/base64 (Upload small file as Base64)

Description: Creates temporary file using base64 source data. You may use this temporary file URL with other API methods. Temporary files are automatically permanently removed after 1 hour. GET or POST request.

Status Errors

Example

Sample Request:

! Don’t forget to set x-api-key url param or http header param (preferred) to API key, get yours here

POST

{
	"file" : "data:image/gif;base64,R0lGODlhEAAQAPUtACIiIScnJigoJywsLDIyMjMzMzU1NTc3Nzg4ODk5OTs7Ozw8PEJCQlBQUFRUVFVVVVhYWG1tbXt7fInDRYvESYzFSo/HT5LJVJPJVJTKV5XKWJbKWZbLWpfLW5jLXJrMYaLRbaTScKXScKXScafTdIGBgYODg6alprLYhbvekr3elr3el9Dotf///wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH5BAAAAAAAIf8LSW1hZ2VNYWdpY2sNZ2FtbWE9MC40NTQ1NQAsAAAAABAAEAAABpJAFGgkKhpFIRHpw2qBLJiLdCrNTFKt0wjD2Xi/G09l1ZIwRJeNZs3uUFQtEwCCVrM1bnhJYHDU73ktJQELBH5pbW+CAQoIhn94ioMKB46HaoGTB5WPaZmMm5wOIRcekqChliIZFXqoqYYkE2SaoZuWH1gmAgsIvr8ICQUPTRIABgTJyskFAw1ZDBAO09TUDw0RQQA7"
}

Endpoint:

Method: POST
Type: POST params, JSON or FORMDATA
URL: https://api.pdf.co/v1/file/upload/base64

Headers:

Body:

More example Requests/Responses:

I. Example Request: https://api.pdf.co/v1/file/upload/base64

Headers:

Body:

I. Example Response: https://api.pdf.co/v1/file/upload/base64

{
    "url": "https://pdf-temp-files.s3.amazonaws.com/a8ac8a3cec3344f08f556bfd2d678b2f/uploadfile.txt",
    "error": false,
    "status": 200,
    "remainingCredits": 98145
}

Status Code: 200

II. Example Request: POST Upload small file as Base64: /file/upload/base64

Headers:

Body:

II. Example Response: POST Upload small file as Base64: /file/upload/base64

{
    "url": "https://pdf-temp-files.s3.amazonaws.com/7588d614c9ad41eb98ec317a02abda63/uploadfile.txt",
    "error": false,
    "status": 200,
    "remainingCredits": 77769
}

Status Code: 200

5. /file/upload/get-presigned-url (GET generate secure URL for upload)

Description: This method generates links to upload your local file to. Use this presignedUrl from the response to upload your file. Once you upload your file to this presignedUrl using PUT, you can use url link to access the uploaded file.

With this method you can upload files up to 2GB in size. Please note that to process these files you should use async=true mode with data extraction and tools endpoints along with /job/check to check status of background jobs you create.

Steps to Upload File:

• First, call /file/upload/get-presigned-url. It will generate link for uploading (presignedUrl) and final link (url)
• Now send your file to the presignedUrl link using PUT method within next 30 minutes.
• Oncce finished, use url to access the file you have just uploaded.

Important: all uploaded files are considered to be temporary files and are automatically permanently removed after 1 hour.

Status Errors

Example

Sample Request:

! Don’t forget to set x-api-key url param or http header param (preferred) to API key, get yours here

GET
https://api.pdf.co/v1/file/upload/get-presigned-url?name=test.pdf&encrypt=true

200
{
    "presignedUrl": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/28e191b14f3a4f43b16fcef1d53d191e/test.pdf?X-Amz-Expires=900&....",
    "url": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/28e191b14f3a4f43b16fcef1d53d191e/test.pdf?X-Amz-Expires=....",
    "error": false,
    "status": 200,
    "name": "test.pdf",
    "remainingCredits": 93574
}

PUT
https://pdf-temp-files.s3-us-west-2.amazonaws.com/28e191b14f3a4f43b16fcef1d53d191e/test.pdf?X-Amz-Expires=900&....
--form 'file=@/path/to/file'

200
{
}

Now you can access your file using link from "url" param to from the first step.

Endpoint:

Method: GET
Type: POST params, JSON or FORMDATA
URL: https://api.pdf.co/v1/file/upload/get-presigned-url

Headers:

Query params:

More example Requests/Responses:

I. Example Request: /file/upload/get-presigned-url

Headers:

Query:

I. Example Response: /file/upload/get-presigned-url

{
    "presignedUrl": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/0c72bf56341142ba83c8f98b47f14d62/test.pdf?X-Amz-Expires=900&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIZJDPLX6D7EHVCKA/20200302/us-west-2/s3/aws4_request&X-Amz-Date=20200302T143951Z&X-Amz-SignedHeaders=host&X-Amz-Signature=8650913644b6425ba8d52b78634698e5fc8970157d971a96f0279a64f4ba87fc",
    "url": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/0c72bf56341142ba83c8f98b47f14d62/test.pdf?X-Amz-Expires=3600&x-amz-security-token=FwoGZXIvYXdzEGgaDA9KaTOXRjkCdCqSTCKBAW9tReCLk1fVTZBH9exl9VIbP8Gfp1pE9hg6et94IBpNamOaBJ6%2B9Vsa5zxfiddlgA%2BxQ4tpd9gprFAxMzjN7UtjU%2B2gf%2FKbUKc2lfV18D2wXKd1FEhC6kkGJVL5UaoFONG%2Fw2jXfLxe3nCfquMEDo12XzcqIQtNFWXjKPWBkQEvmii4tfTyBTIot4Na%2BAUqkLshH0R7HVKlEBV8btqa0ctBjwzwpWkoU%2BF%2BCtnm8Lm4Eg%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA4NRRSZPHEGHTOA4W/20200302/us-west-2/s3/aws4_request&X-Amz-Date=20200302T143951Z&X-Amz-SignedHeaders=host;x-amz-security-token&X-Amz-Signature=243419ac4a9a315eebc2db72df0817de6a261a684482bbc897f0e7bb5d202bb9",
    "error": false,
    "status": 200,
    "name": "test.pdf",
    "remainingCredits": 98145
}

Status Code: 200

II. Example Request: Generate URL for upload: /file/upload/get-presigned-url

Headers:

Query:

II. Example Response: Generate URL for upload: /file/upload/get-presigned-url

{
    "presignedUrl": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/63f7f641a3144f84ac209b4f514bc0df/myFile.png?X-Amz-Expires=900&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIZJDPLX6D7EHVCKA/20200716/us-west-2/s3/aws4_request&X-Amz-Date=20200716T091225Z&X-Amz-SignedHeaders=host&X-Amz-Signature=14d3eb91305d96804deccb6985cbbd4552705f5ddb2144b901a97c8e7abc1ac3",
    "url": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/63f7f641a3144f84ac209b4f514bc0df/myFile.png?X-Amz-Expires=3600&x-amz-security-token=FwoGZXIvYXdzECMaDC5PzTA618EQiHoskyKBAeYQcVKbK%2B0F5nnjBV6MKbPNvueaFlSBSPxPi31BdtFzw1jAIXjAvATkBwTPRx%2FVwhszDtYQRVkbhsZF6HLotVUedrcdGHOrsWV5DpN2xKgnX7xRcJrvUu0wieaJHDmHzFL1eNzFwj2927L%2BtadEfmz1a0SiEImJZujcLF78lJZ5mSj7s8D4BTIok4Xja8wyqnBBp2EOcZw8qrUxeR7Ufd0aw4bf7Z1Cur1f0PFg8hlrYQ%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA4NRRSZPHAPA4HUJS/20200716/us-west-2/s3/aws4_request&X-Amz-Date=20200716T091225Z&X-Amz-SignedHeaders=host;x-amz-security-token&X-Amz-Signature=26e27b48c5284665914fdd981d7b0b5b6e70e64839f28621f3dc82256e492879",
    "error": false,
    "status": 200,
    "name": "myFile.png",
    "remainingCredits": 77779
}

Status Code: 200

6. /file/upload/url (Upload file from URL)

Description: Downloads file from a source url and uploads it as a temporary file. Temporary files are automatically permanently removed after 1 hour.

Status Errors

Example

Sample Request:

! Don’t forget to set x-api-key url param or http header param (preferred) to API key, get yours here

POST

{
"url" : "https://bytescout-com.s3.amazonaws.com/files/demo-files/cloud-api/pdf-split/sample.pdf"
}

Endpoint:

Method: POST
Type: POST params, JSON or FORMDATA
URL: https://api.pdf.co/v1/file/upload/url

Headers:

Body:

More example Requests/Responses:

I. Example Request: /file/upload/url

Headers:

Body:

I. Example Response: /file/upload/url

{
    "url": "https://pdf-temp-files.s3.amazonaws.com/1a4a92ac805c41c28ef75a24e0f35ba5/sample.pdf",
    "error": false,
    "status": 200,
    "name": "sample.pdf",
    "remainingCredits": 98145
}

Status Code: 200

II. Example Request: POST Upload from URL: /file/upload/url

Headers:

Body:

II. Example Response: POST Upload from URL: /file/upload/url

{
    "url": "https://pdf-temp-files.s3.amazonaws.com/4e36f2962b7f4248b7167f4389d534d5/sample.pdf",
    "error": false,
    "status": 200,
    "name": "sample.pdf",
    "remainingCredits": 77767
}

Status Code: 200

7. /file/upload/url (Upload from URL)

Description: Downloads file from a source url and uploads it as a temporary file. Temporary files are automatically permanently removed after 1 hour.

Status Errors

Example

Sample Request:

! Don’t forget to set x-api-key url param or http header param (preferred) to API key, get yours here

POST

{
"url" : "https://bytescout-com.s3.amazonaws.com/files/demo-files/cloud-api/pdf-split/sample.pdf"
}

Endpoint:

Method: GET
Type: POST params, JSON or FORMDATA
URL: https://api.pdf.co/v1/file/upload/url

Headers:

Query params:

More example Requests/Responses:

I. Example Request: /file/upload/url

Headers:

I. Example Response: /file/upload/url

{
    "url": "https://pdf-temp-files.s3.amazonaws.com/703aa298cfe745baa3449fbdaba4d1d7/sample.pdf",
    "error": false,
    "status": 200,
    "name": "sample.pdf",
    "remainingCredits": 98145
}

Status Code: 200

II. Example Request: GET Upload from URL: /file/upload/url

Headers:

Query:

II. Example Response: GET Upload from URL: /file/upload/url

{
    "url": "https://pdf-temp-files.s3.amazonaws.com/97415d1c45a04b29ac42c8dc01883316/sample.pdf",
    "error": false,
    "status": 200,
    "name": "sample.pdf",
    "remainingCredits": 77765
}

Status Code: 200

8. PUT presignedUrl –formdata file=..

With this method you can upload files up to 2GB in size. Please note that to process these files you should use async=true mode with data extraction and tools endpoints along with /job/check to check status of background jobs you create.

Steps to Upload File:

• First, call /file/upload/get-presigned-url. It will generate link for uploading (presignedUrl) and final link (url)
• Now send your file to the presignedUrl link using PUT method within next 30 minutes.
• Oncce finished, use url to access the file you have just uploaded.

Important: all uploaded files are considered to be temporary files and are automatically permanently removed after 1 hour.

Status Errors

Workflow

Sample Request:

! Don’t forget to set x-api-key url param or http header param (preferred) to API key, get yours here

Generate secure link where you will upload your file:
GET
https://api.pdf.co/v1/file/upload/get-presigned-url?name=test.pdf&encrypt=true

200
{
    "presignedUrl": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/28e191b14f3a4f43b16fcef1d53d191e/test.pdf?X-Amz-Expires=900&....",
    "url": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/28e191b14f3a4f43b16fcef1d53d191e/test.pdf?X-Amz-Expires=....",
}

Now all PUT to upload file to "presignedUrl" you've got:
https://pdf-temp-files.s3-us-west-2.amazonaws.com/28e191b14f3a4f43b16fcef1d53d191e/test.pdf?X-Amz-Expires=900&....
--form 'file=@/path/to/file'

200
{
}

Now your file is available via link from "url" param from the first step

Endpoint:

Method: PUT
Type: POST params, JSON or FORMDATA
URL: <insert presignedUrl generated by https://api.pdf.co/v1/file/upload/get-presigned-url >

Headers:

Body:

More example Requests/Responses:

I. Example Request: PUT Upload File PUT presignedUrl –formdata file=..

Headers:

Body:

Status Code: 200

II. Example Request: /file/upload/get-presigned-url

Headers:

Query:

II. Example Response: /file/upload/get-presigned-url

{
    "presignedUrl": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/0c72bf56341142ba83c8f98b47f14d62/test.pdf?X-Amz-Expires=900&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIZJDPLX6D7EHVCKA/20200302/us-west-2/s3/aws4_request&X-Amz-Date=20200302T143951Z&X-Amz-SignedHeaders=host&X-Amz-Signature=8650913644b6425ba8d52b78634698e5fc8970157d971a96f0279a64f4ba87fc",
    "url": "https://pdf-temp-files.s3-us-west-2.amazonaws.com/0c72bf56341142ba83c8f98b47f14d62/test.pdf?X-Amz-Expires=3600&x-amz-security-token=FwoGZXIvYXdzEGgaDA9KaTOXRjkCdCqSTCKBAW9tReCLk1fVTZBH9exl9VIbP8Gfp1pE9hg6et94IBpNamOaBJ6%2B9Vsa5zxfiddlgA%2BxQ4tpd9gprFAxMzjN7UtjU%2B2gf%2FKbUKc2lfV18D2wXKd1FEhC6kkGJVL5UaoFONG%2Fw2jXfLxe3nCfquMEDo12XzcqIQtNFWXjKPWBkQEvmii4tfTyBTIot4Na%2BAUqkLshH0R7HVKlEBV8btqa0ctBjwzwpWkoU%2BF%2BCtnm8Lm4Eg%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA4NRRSZPHEGHTOA4W/20200302/us-west-2/s3/aws4_request&X-Amz-Date=20200302T143951Z&X-Amz-SignedHeaders=host;x-amz-security-token&X-Amz-Signature=243419ac4a9a315eebc2db72df0817de6a261a684482bbc897f0e7bb5d202bb9",
    "error": false,
    "status": 200,
    "name": "test.pdf",
    "remainingCredits": 98145
}

Status Code: 200

PDF Add Text and Images to PDF

Add text, images, links to PDF files. You can update or modify PDF and scanned PDF files.

Interactive helper tool: PDF viewer displaying X and Y coordinates.

1. /pdf/edit/add

adds text, images, text fields, unchecked checkbox, checked checkbox to existing PDF file. You can fill out out existing PDF forms and documents and create new fillable PDF forms using this method.

To find X and Y coordinates for placing text, images or objects please use special PDF viewer displaying X and Y coordinates.

• url required. URL to the source file. Supports links from Google Drive, Dropbox and from built-in PDF.co files storage. For uploading files via API please check Files Upload section.

• annotations[]. optional. Array of text objects to be added on top of pdf. Text objects can be ready-only ("type": "text" by default), input pdf input fields ("type": "textField") or checkboxes ("type": "checkbox"). Sample:

  "annotations":
  [
        {
            "text": "Testing Clickable Links \r\n(CLICK ME!)",
            "x": 200,
            "y": 200,
            "size": 24,
            "pages": "0-",
            "color": "CCBBAA",
            "link": "https://bytescout.com/"
        },
        {
            "text": "Testing Clickable Links \r\n(CLICK ME!)",
            "x": 200,
            "y": 200,
            "size": 24,
            "pages": "0-",
            "color": "CCBBAA",
            "link": "https://bytescout.com/",
            "fontName": "Colibri",
            "fontItalic": true,
            "fontBold": true,
            "fontStrikeout": false,
            "fontUnderline": true,
            "type": "text"
        },
        {
            "text": "sample pdf input field with prefilled text",
            "x": 10,
            "y": 30,
            "size": 12,
            "pages": "0-",
            "type": "TextField",
            "id": "textfield1"
        },
        {
            "x": 100,
            "y": 150,
            "size": 12,
            "pages": "0-",
            "type": "Checkbox",
            "id": "checkbox2"
        }
  ]
  

  See font list for all PDF.co supported fonts.

• images[] optional. Array of image objects to be added on top of PDF file. Images can be loaded from URL or from URLs for internal file storage. Sample:

  "images": [
        {
            "url": "bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/logo.png",
            "x": 200,
            "y": 250,
            "pages": "0",
            "link": "www.pdf.co"
        }    
  ]
  

• fields[] optional. Array of values to update filable pdf fields in input pdf. You can create your own automated PDF filler for your pdf forms using this array. Sample:

  "fields: 
  [
        {
            "fieldName": "topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1]",
            "pages": "1",
            "text": "True"
        },
        {
            "fieldName": "topmostSubform[0].Page1[0].FilingStatus[0].c1_01[1]",
            "pages": "1",
            "text": "True"
        }
  ]        
  

• password optional. Password of PDF file. Must be a String
• async optional. Runs processing asynchronously. Returns Use JobId that you may use with /job/check to check state of the processing (possible states: working, failed, aborted and success). Must be one of: true, false.
• encrypt optional. Enable encryption for output file. Must be one of: true, false.

• name optional. File name for generated output. Must be a String.

• profiles optional. Must be a String. You can set additional and extra options using this parameter that allows you to set custom configuration. See profiles samples for examples.

Endpoint:

Method: POST
Type: RAW
URL: https://api.pdf.co/v1/pdf/edit/add

Headers:

Body:

{
    "async": false,
    "encrypt": true,
    "name": "newDocument",
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/sample.pdf",
    "annotations": [
        {
            "text": "Testing, one, two, three.",
            "x": 10,
            "y": 10,
            "size": 12,
            "pages": "0-"
        },
        {
            "text": "Testing Clickable Links \r\n(CLICK ME!)",
            "x": 200,
            "y": 200,
            "size": 24,
            "pages": "0-",
            "color": "CCBBAA",
            "link": "https://bytescout.com/",
            "fontName": "Colibri",
            "fontItalic": true,
            "fontBold": true,
            "fontStrikeout": false,
            "fontUnderline": true
        },
        {
            "text": "Simple text label (default type)",
            "x": 100,
            "y": 100,
            "size": 12,
            "pages": "0-",
            "type": "Text"
        },
        {
            "text": "sample prefilled text",
            "x": 10,
            "y": 30,
            "size": 12,
            "pages": "0-",
            "type": "TextField",
            "id": "textfield1"
        },
        {
            "x": 100,
            "y": 150,
            "size": 12,
            "pages": "0-",
            "type": "Checkbox",
            "id": "checkbox2"
        },
        {
            "x": 100,
            "y": 170,
            "size": 12,
            "pages": "0-",
            "link": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/logo.png",
            "type": "CheckboxChecked",
            "id": "checkbox3"
        }
    ],
    "images": [
        {
            "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/logo.png",
            "x": 450,
            "y": 10,
            "pages": "0"
        },
        {
            "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/logo.png",
            "x": 450,
            "y": 100,
            "width": 50,
            "height": 50,
            "pages": "0"
        },
        {
            "url": "bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/logo.png",
            "x": 200,
            "y": 250,
            "pages": "0",
            "link": "www.pdf.co"
        }
    ]
}

More example Requests/Responses:

I. Example Request: POST /pdf/edit/add

Headers:

Body:

{
    "async": false,
    "encrypt": true,
    "name": "newDocument",
    "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/sample.pdf",
    "annotations":[
        {
            "text":"Testing, one, two, three.",
            "x": 10,
            "y": 10,
            "size": 12,
            "pages": "0-"
        },
        {
            "text":"Testing Clickable Links \r\n(CLICK ME!)",
            "x": 200,
            "y": 200,
            "size": 24,
            "pages": "0-",
            "color": "CCBBAA",
            "link": "https://bytescout.com/"
        },
      {
            "text":"Simple text label (default type)",
            "x": 100,
            "y": 100,
            "size": 12,
            "pages": "0-",
            "type": "Text"
        },
       {
            "text":"sample prefilled text",
            "x": 10,
            "y": 30,
            "size": 12,
            "pages": "0-",
            "type": "TextField",
            "id": "textfield1"
        },
              {
            "x": 100,
            "y": 150,
            "size": 12,
            "pages": "0-",
            "type": "Checkbox",
            "id": "checkbox2"
        },
              {
            "x": 100,
            "y": 170,
            "size": 12,
            "pages": "0-",
            "link": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/logo.png",
            "type": "CheckboxChecked",
            "id":"checkbox3"
        }          
        
    ],
    
    "images": [
        {
            "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/logo.png",
            "x": 450,
            "y": 10,
            "pages": "0"
        },
        {
            "url": "https://bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/logo.png",
            "x": 450,
            "y": 100,
            "width": 50,
            "height": 50,
            "pages": "0"
        },
        {
            "url": "bytescout-com.s3-us-west-2.amazonaws.com/files/demo-files/cloud-api/pdf-edit/logo.png",
            "x": 200,
            "y": 250,
            "pages": "0",
            "link": "www.pdf.co"
        }
        
    ]
}