AI Invoice Parser

`POST /ai-invoice-parser`

The AI Invoice parser automatically detects invoice layouts without the manual effort previously required to supply document parsing templates for reference.

Important

Only invoices will be parsed. For all other documents, please use our existing Document Parser.
To ensure accurate processing, each invoice must be clearly separated. If an invoice contains multiple pages, we recommend splitting it into individual PDFs using the PDF Split API.
While AI Invoice Parser supports multi-page invoices, the total page count for a single PDF must not exceed 100 pages. Submitting large PDFs containing multiple invoices is not recommended.
To retrieve results, you must poll the Background Job Check endpoint using the jobId returned in the initial response. Once the job status is marked as success, the output file will be available at the provided URL.

This method extracts data from your PDF invoices and returns a well-structured JSON format for your use.

Attributes

Attributes are case-sensitive and should be inside JSON for POST request. for example: { "url": "https://example.com/file1.pdf" }

Attribute	Type	Required	Default	Description
`url`	string	Yes	-	URL to the source file `url attribute`
`customField`	string	No	-	JSON string containing custom field names to extract. Use `camelCase` for field names (e.g., `storeNumber`, `deliveryDate`). Multiple fields should be comma-separated.
`callback`	string	No	-	The callback URL (or Webhook) used to receive the POST data. see Webhooks & Callbacks. This is only applicable when `async` is set to `true`.
`profiles`	object	No	-	See Profiles for more information.
`DataEncryptionAlgorithm`	string	No	-	Controls the encryption algorithm used for data encryption. See User-Controlled Encryption for more information. The available algorithms are: `AES128`, `AES192`, `AES256`.
`DataEncryptionKey`	string	No	-	Controls the encryption key used for data encryption. See User-Controlled Encryption for more information.
`DataEncryptionIV`	string	No	-	Controls the encryption IV used for data encryption. See User-Controlled Encryption for more information.
`DataDecryptionAlgorithm`	string	No	-	Controls the decryption algorithm used for data decryption. See User-Controlled Encryption for more information. The available algorithms are: `AES128`, `AES192`, `AES256`.
`DataDecryptionKey`	string	No	-	Controls the decryption key used for data decryption. See User-Controlled Encryption for more information.
`DataDecryptionIV`	string	No	-	Controls the decryption IV used for data decryption. See User-Controlled Encryption for more information.

Custom Fields

AI Invoice Parser with custom fields support automatically detects invoice layouts and extracts both standard schema data and user-specified custom fields without requiring manual templates. The customField parameter allows you to specify additional fields to extract beyond the standard schema. Some examples include:

storeNumber - Store or branch identifier
deliveryDate - Expected delivery date
financialCharges - Additional financial charges
lineTotal - Total amount for line items
purchaseOrderRef - Purchase order reference number
customerReference - Customer reference number
departmentCode - Department or cost center code

If a custom field returns an empty value, please contact our support team to help improve the extraction accuracy.

Query parameters

No query parameters accepted.

Responses

Parameter	Type	Description
`status`	string	Status of the API response. The statuses are: `success`, `error`.
`message`	string	Descriptive message for the response status.
`pageCount`	integer	Number of pages processed or returned.
`body`	object	Contains the invoice data. See Invoice Schema for more information.
`jobId`	string	Unique identifier for the background job.
`credits`	integer	Credits used for this operation.
`remainingCredits`	integer	Credits left after this job execution.
`duration`	integer	Time taken to complete the request, in milliseconds.

Invoice Schema

The body object contains all the metadata needed to understand your invoice content and includes the following attributes:

"body": {
  "vendor": { .... },
  "customer": { .... },
  "invoice": { .... },
  "paymentDetails": { .... },
  "others": { .... },
  "lineItems": { .... }
}

The `vendor` Object

An object containing vendor details.

Attribute	Type	Description
`name`	string	Name of the vendor
`address`	object	Vendor’s address details. See address object
`contactInformation`	object	Vendor contact details. See contactInformation object
`entityId`	object	Vendor’s entity ID (e.g., EIN, ABN, VAT, GST, etc.)

The `customer` Object

An object containing customer details.

Attribute	Type	Description
`billTo`	object	Billing details. See customer.billTo
`shipTo`	object	Shipping details. See customer.shipTo

`customer.billTo`

Attribute	Type	Description
`name`	string	Customer name
`address`	object	See address object
`contactInformation`	object	See contactInformation object
`entityId`	string	Customer’s entity ID (e.g., EIN, ABN, VAT, GST, etc.)

`customer.shipTo`

Attribute	Type	Description
`name`	string	Customer name
`address`	object	See address object

The `invoice` Object

An object containing the invoice details.

Attribute	Type	Description
`invoiceNo`	string	Invoice number
`invoiceDate`	string	Date of invoice
`poNo`	string	Purchase order number
`orderNo`	string	Sales order number

The `paymentDetails` Object

An object containing payment details.

Attribute	Type	Description
`paymentTerms`	string	Terms of payment
`dueDate`	string	Payment due date
`total`	string	Total amount due
`subtotal`	string	Subtotal amount
`tax`	string	Tax amount
`discount`	string	Discount amount
`shipping`	string	Shipping amount
`bankingInformation`	object	See bankingInformation

`paymentDetails.bankingInformation`

Attribute	Type	Description
`bankName`	string	Name of the bank
`accountHolderName`	string	Name of the account holder
`accountNumber`	string	Bank account number
`iban`	string	International Bank Account Number (IBAN)
`swiftBicCode`	string	SWIFT/BIC code of the bank
`bankAddress`	object	See address object
`bankRoutingCode`	string	Routing code for domestic payments
`bankCode`	string	Institution number within Canadian banking network
`branchNumber`	string	Branch-specific code
`purposeCode`	string	Specifies the transaction’s intent
`additionalNotes`	string	Payment instructions or other notes

The `others` Object

An object containing additional notes.

Attribute	Type	Description
`notes`	string	Additional notes such as delivery instructions

The `lineItems` Object

An object detailing the line items in an invoice.

Note: there is no common structure due to significant variability between invoices!

A typical invoice might list purchase items with details such as name, quantity or price of each individual item.

Common Objects

There are a couble of objects which are commonly used in the schema in a few places, these are as follows.

`address` object

Attribute	Type	Description
`streetAddress`	string	Street address
`city`	string	City name
`state`	string	State/county name
`postalCode`	string	Postal/ZIP code
`country`	string	Country code/name

`contactInformation` object

Attribute	Type	Description
`phone`	string	Phone number of the vendor
`fax`	string	Fax number of the vendor
`email`	string	Email address of the vendor

`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/document-parser/sample-invoice.pdf",
  "callback": "https://example.com/callback/url/you/provided"
}

`Example` Response

To see the main response codes, please refer to the Response Codes.

You can use jobId to identify the corresponding callback response. Use the Job Check API to poll the job status.

{
  "error": false,
  "status": "created",
  "jobId": "7830deca-2e66-11ef-9ad3-8eff830e7461",
  "credits": 100,
  "remainingCredits": 106674,
  "duration": 33
}

`Example` Callback Response

{
  "status": "success",
  "message": "Success",
  "pageCount": 1,
  "body": {
    "vendor": {
      "name": "ACME Inc.",
      "address": {
        "streetAddress": "1540  Long Street",
        "city": "Jacksonville",
        "state": "FL",
        "postalCode": "32099",
        "country": "US"
      },
      "contactInformation": {
        "phone": "352-200-0371",
        "fax": "904-787-9468"
      }
    },
    "customer": {
      "billTo": {
        "name": "Lanny Lane Ltd.",
        "address": {
          "streetAddress": "82  Gorby Lane",
          "city": "Columbia",
          "state": "IN",
          "postalCode": "39429",
          "country": "US"
        }
      },
      "shipTo": {
        "name": "Same as recipient"
      }
    },
    "invoice": {
      "invoiceNo": "67893566",
      "invoiceDate": "JAN 5, 2025"
    },
    "paymentDetails": {
      "total": "$1,272.35",
      "subtotal": "$1,262.35",
      "tax": "$10.00",
      "shipping": "$0.00"
    },
    "lineItems": [
      [
        {
          "quantity": "2",
          "description": "Item 1",
          "unit_price": "9.95",
          "total": "19.90"
        },
        {
          "quantity": "5",
          "description": "Item 2",
          "unit_price": "20.00",
          "total": "100.00"
        },
        {
          "quantity": "1",
          "description": "Item 3",
          "unit_price": "19.95",
          "total": "19.95"
        },
        {
          "quantity": "1",
          "description": "Item 4",
          "unit_price": "123.00",
          "total": "123.00"
        },
        {
          "quantity": "10",
          "description": "Item 5",
          "unit_price": "99.95",
          "total": "999.50"
        }
      ]
    ]
  },
  "jobId": "7830deca-2e66-11ef-9ad3-8eff830e7461",
  "credits": 100,
  "remainingCredits": 106472,
  "duration": 33
}

Setting up the Callback URL

The callback URL should be a webhook which listens to responses from the parsing results. You can setup your own webhook or use one from a provider.

If you are unsure about webhooks or callbacks, please read this Wikipedia article to get started.

Supported Languages

Albanian (Shqip)
Bosnian (Bosanski)
Bulgarian (Български)
Croatian (Hrvatski)
Czech (Čeština)
Danish (Dansk)
Dutch (Nederlands)
English
Estonian (Eesti)
Finnish (Suomi)
French (Français)
German (Deutsch)
Greek (Ελληνικά)
Hungarian (Magyar)
Icelandic (Íslenska)
Italian (Italiano)
Latvian (Latviešu)
Lithuanian (Lietuvių)
Norwegian (Norsk)
Polish (Polski)
Portuguese (Português)
Romanian (Română)
Russian (Русский)
Serbian (Српски)
Slovak (Slovenčina)
Slovenian (Slovenščina)
Spanish (Español)
Swedish (Svenska)
Turkish (Türkçe)
Ukrainian (Українська)

Inconsistent URL Encoding in cURL Output: When using cURL to make API requests, the output JSON may show URL characters encoded as Unicode escape sequences. For example, the ampersand character (&) may appear as \u0026 in the cURL output. This is normal JSON encoding behavior and does not affect the validity of the URL. The URL will function correctly when used, as JSON parsers automatically decode these escape sequences. If you’re parsing the response programmatically, your JSON parser will handle this conversion automatically.

Code Samples

CURL
JavaScript/Node.js
Python
C#
Java
PHP

curl -X POST \
https://api.pdf.co/v1/ai-invoice-parser

Welcome

Extraction

Editing

PDF Conversion

Excel Conversion

PDF Merging & Splitting

Forms

Find & Search

Document, File & System

Pages

Barcodes

Glossary

`POST /ai-invoice-parser`

Attributes

Custom Fields

Query parameters

Responses

Invoice Schema

Sections

The `vendor` Object

The `customer` Object

`customer.billTo`

`customer.shipTo`

The `invoice` Object

The `paymentDetails` Object

`paymentDetails.bankingInformation`

The `others` Object

The `lineItems` Object

Common Objects

`address` object

`contactInformation` object

`Example` Payload

`Example` Response

`Example` Callback Response

Setting up the Callback URL

Supported Languages

Code Samples

Welcome

Extraction

Editing

PDF Conversion

Excel Conversion

PDF Merging & Splitting

Forms

Find & Search

Document, File & System

Pages

Barcodes

Glossary

​POST /ai-invoice-parser

​Attributes

​Custom Fields

​Query parameters

​Responses

​Invoice Schema

​Sections

​The vendor Object

​The customer Object

​customer.billTo

​customer.shipTo

​The invoice Object

​The paymentDetails Object

​paymentDetails.bankingInformation

​The others Object

​The lineItems Object

​Common Objects

​address object

​contactInformation object

​Example Payload

​Example Response

​Example Callback Response

​Setting up the Callback URL

​Supported Languages

​Code Samples

`POST /ai-invoice-parser`

Attributes

Custom Fields

Query parameters

Responses

Invoice Schema

Sections

The `vendor` Object

The `customer` Object

`customer.billTo`

`customer.shipTo`

The `invoice` Object

The `paymentDetails` Object

`paymentDetails.bankingInformation`

The `others` Object

The `lineItems` Object

Common Objects

`address` object

`contactInformation` object

`Example` Payload

`Example` Response

`Example` Callback Response

Setting up the Callback URL

Supported Languages

Code Samples