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.

Please ensure that your PDF file does not exceed 100 pages. Files containing more than 100 pages will not be processed.
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" }
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.
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
statusstringStatus of the API response. The statuses are: success, error.
messagestringDescriptive message for the response status.
pageCountintegerNumber of pages processed or returned.
bodyobjectContains the invoice data. See Invoice Schema for more information.
jobIdstringUnique identifier for the background job.
creditsintegerCredits used for this operation.
remainingCreditsintegerCredits left after this job execution.
durationintegerTime 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": { .... }
}

Sections


The vendor Object

An object containing vendor details.

AttributeTypeDescription
namestringName of the vendor
addressobjectVendor’s address details. See address object
contactInformationobjectVendor contact details. See contactInformation object
entityIdobjectVendor’s entity ID (e.g., EIN, ABN, VAT, GST, etc.)

The customer Object

An object containing customer details.

AttributeTypeDescription
billToobjectBilling details. See customer.billTo
shipToobjectShipping details. See customer.shipTo

customer.billTo

AttributeTypeDescription
namestringCustomer name
addressobjectSee address object
contactInformationobjectSee contactInformation object
entityIdstringCustomer’s entity ID (e.g., EIN, ABN, VAT, GST, etc.)

customer.shipTo

AttributeTypeDescription
namestringCustomer name
addressobjectSee address object

The invoice Object

An object containing the invoice details.

AttributeTypeDescription
invoiceNostringInvoice number
invoiceDatestringDate of invoice
poNostringPurchase order number
orderNostringSales order number

The paymentDetails Object

An object containing payment details.

AttributeTypeDescription
paymentTermsstringTerms of payment
dueDatestringPayment due date
totalstringTotal amount due
subtotalstringSubtotal amount
taxstringTax amount
discountstringDiscount amount
shippingstringShipping amount
bankingInformationobjectSee bankingInformation

paymentDetails.bankingInformation

AttributeTypeDescription
bankNamestringName of the bank
accountHolderNamestringName of the account holder
accountNumberstringBank account number
ibanstringInternational Bank Account Number (IBAN)
swiftBicCodestringSWIFT/BIC code of the bank
bankAddressobjectSee address object
bankRoutingCodestringRouting code for domestic payments
bankCodestringInstitution number within Canadian banking network
branchNumberstringBranch-specific code
purposeCodestringSpecifies the transaction’s intent
additionalNotesstringPayment instructions or other notes

The others Object

An object containing additional notes.

AttributeTypeDescription
notesstringAdditional 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

AttributeTypeDescription
streetAddressstringStreet address
citystringCity name
statestringState/county name
postalCodestringPostal/ZIP code
countrystringCountry code/name

contactInformation object

AttributeTypeDescription
phonestringPhone number of the vendor
faxstringFax number of the vendor
emailstringEmail 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.

Code Samples

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