Invoice and Document Capturing API Reference API Reference

General Information
The BLU DELTA API is a machine and deep learning-based invoice and document capturing solution (cloud or onpremise). An image or pdf file is converted into structured json data containing document specific details. It works for certain doc-types out-of-the-box with recognition rates up to 98% (without any training). However, it can be improved via training as well.
The API returns document and invoice details (e.g. like an invoice or document date, invoice id, gross/net amounts, VATs, and many more fields) as well as plain full text and a generated pdf highlighting details. By default BLU DELTA API does NOT store any received data!

API Endpoint
The API Endpoint gets called via https://api.bludelta.ai/ + Version. E.g. https://api.bludelta.ai/v1-18

API Access Token
Request a free api key for the BLU DELTA document capturing cloud here.

OpenAPI specification
Provided with every release under https://api.bludelta.ai/version/openapi or you find direct link at BLU DELTA Invoice and Document Capturing Dev Center.

Further developer info
BLU DELTA Invoice and Document Capturing Dev Center

Further product info and offerings
BLU DELTA Invoice and Document Capturing website.

No Developer? Test API directly on our website: BLU DELTA invoice capturing trial page

Supported Invoice and Document Details

Title	Description	Response Type	Id	Notice
Document Type	Classify document to Invoice/CreditMemo/Other	DetectionResponse	8192	Value: Invoice, CreditMemo or Other
Invoice Currency	Main currency of invoice	DetectionResponse	524288	ISO Code 4217
Invoice Id	Document identifier	DetectionResponse	1024
Invoice Date	Date of issue	DetectionResponse	64	YYYY-MM-DD (ISO 8601)
Grand Total Amount	Grand total amount	DetectionResponse	16	decimal separator '.', no group separator, two decimal digits
Vat Group	Vat rate Net amount Vat amount	DetectionGroupResponse	536870912	for each vat detail: one DetectionResponse
Net Total Amount	Total net amount	DetectionResponse	256	deprecated Use Vat Groups instead to calculate total net amount
Vat Total Amount	Total vat amount	DetectionResponse	1073741824	deprecated Use Vat Groups instead to calculate total vat amount
Iban	Iban	DetectionResponse	16384	for each Iban: one DetectInvoiceResponse
Bic	Bic	DetectionResponse	32768	for each Bic: one DetectInvoiceResponse
Bank Group	Bank Code Bank Account	DetectionGroupResponse	17179869184	for each bank detail: one DetectionResponse
Due Date Group	Due Date Date Due Date Duration	DetectionGroupResponse	17592186044416	for each due date detail: one DetectionResponse
Discount Group	Discount Date Discount Duration Discount Percent	DetectionGroupResponse	1099511627776	for each discount detail: one DetectionResponse
UId	Vat Id classified for Sender or Receiver or other	DetectionResponse	8388608	Sender/Receiver classification is returned in Name property (SenderVatId, ReceiverVatId, VatId)
Customer Id	Customer Identifier	DetectionResponse	2097152
Tax Number	German Tax Number	DetectionResponse	4194304	deprecated Use TaxId (SenderTaxId) instead
TaxId	Tax Id classified for Sender or Receiver or other	DetectionResponse	2305843009213693952	TaxId field for international company ids when vat id is not available. Sender/Receiver classification is returned in Name property (SenderTaxId, ReceiverTaxId, TaxId)
TaxId	Tax Id classified for Sender or Receiver or other	DetectionResponse	2305843009213693952	TaxId field for international company ids when vat id is not available. Sender/Receiver classification is returned in Name property (SenderTaxId, ReceiverTaxId, TaxId)
Delivery Note Id	Delivery Note Identifier in header	DetectionResponse	1048576	single identifier in header
Delivery Date	Delivery Date	DetectionResponse	8	single date - no timespan
Receiver Order Id	Order Identifier of Receiver in header	DetectionResponse	33554432	single identifier in header
Receiver Order Date	Order Date of Receiver	DetectionResponse	134217728
Sender Order Id	Order Identifier of Sender	DetectionResponse	16777216
Sender Order Date	Order Date of Sender	DetectionResponse	67108864
ISR Reference	Swiss inpayment slip reference	DetectionResponse	34359738368
ISR Subscriber	ISR customer number	DetectionResponse	35184372088832
KID Number	KID number is used in Norway for payment identification	DetectionResponse	70368744177664
Company Registration Number	Local company registration number for Sender or Receiver. Currently only supported for Czechia.	DetectionResponse	140737488355328
Sender Name	Name of Sender	DetectionResponse	2	deprecated Use name of Sender contact instead
Sender Contact	Contact information of Sender	ContactResponse	2	Name, Address, Email, ...
Receiver Contact	Contact information of Sender	ContactResponse	128	Name, Address, Email, ...
Contacts	A list of all contacts that where found on the invoice - including the sender and receiver contacts.	List of ContactResponse	281474976710656	Each contact consists of: Name, Address, Email, ...
Line Items	Line item table	LineItemTableResponse	65536	Each line item (LineItemResponse) contains: PositionNumber, PositionId, ItemId, Description, OrderId, DeliveryId, DeliveryDate, Quantity, Unit, UnitPrice, VatRate, Discount, TotalAmount
Delivery Period Group	Delivery Period Date Start Delivery Period Date End	DetectionGroupResponse	4503599627370496	for each delivery period detail: one DetectionResponse
Cost Center	Cost Center Identifier	DetectionResponse	9007199254740992
Vat Exemption	Vat Exemption	DetectionResponse	18014398509481984
Qr Code Group	Qr Code Raw String Qr Code Detail	DetectionGroupResponse	144115188075855872	Always has the Raw String. Has Details if the Qr Code can be parsed. Has to be enabled per customer. Supported Codes: SwissQr, CodigoQr, ChineseQR, IndianQR, PeruQR, GenericQR.
Qr Code Raw String	Qr Code Raw String	DetectionResponse	36028797018963968
Qr Code Detail	Qr Code Detail	DetectionResponse	72057594037927936	Depending on type of found Qr Code these are the parsed details found.
Whitelist Group	Whitelist Value Whitelist Hint	DetectionGroupResponse	1152921504606846976	Always has the value and at least one hint, that lead to the specific value. Has to be enabled via Whitelist-Plugin or Client/Supplier-Processing.
Whitelist Value	Whitelist Value	DetectionResponse	288230376151711744	First column of given csv (Id Field).
Whitelist Hint	Whitelist Hint	DetectionResponse	576460752303423488	All the hints found to indicate the value of the group.
Bar Code Group	Bar Code Group	DetectionGroupResponse	-9223372036854775808	A bar code group has either type name "Boleto" or "BarCode". It contains a 'Bar' detail which contains the raw barcode value.
Bar Code Detail	Bar Code Detail	DetectionGroupResponse	4611686018427387904	Bar code detail with type name 'Bar' contains the raw barcode value.
EInvoice	EInvoice	EInvoiceResponse		EInvoice provides key details of an electronic invoice, such as a generated PDF representation of the XInvoice XML file, facilitating visualization and document management.

API Endpoint

https://api.bludelta.ai/v1-18

Request Content-Types: application/json

Request Custom Header

X-ApiKey: YOUR_API_KEY

The API Key is used to authenticate and authorize the use of the BLU DELTA API. If you have not received an API key yet: You can request a free trial from bludelta-support@blumatix.at

e.g. "fmHjlBM+nzRN4VQxgnZx9HdixhYXXXXeqHsx6a3Dso03QNKyXXXXyML0KODbNY9T9mfeFU6jZLv+xeuXDLaHig=="

X-ApiIdentifier: YOUR_API_IDENTIFIER (optional)

The API Identifier can be used to track the usage of sub-customers (e.g. platforms or partners have again customers and want to track the usage of their customers).
If you need this flexibility then please contact our support team: bludelta-support@blumatix.at

e.g. "partner.customer"

Attention: Depending on the configuration of your API key, you may have to send a predefined identifier here.

Response Content-Types: application/json

Schemes: http, https

Version: 1.18.x

API Json Response (exemplary)


    {
                                "DocumentResolution": <integer>,
                                "DocumentFormat": <string>,
                                "Language": "<string>",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {..."TypeName": "DocumentType"...},
    {..."TypeName": "InvoiceId"...},
    {..."TypeName": "SenderOrderId"...},
    {..."TypeName": "CustomerId"...},
    {..."TypeName": "InvoiceDate"...},
    {..."TypeName": "SenderOrderDate"...},
    {..."TypeName": "ReceiverOrderDate"...},
    {..."TypeName": "DeliveryDate"...},
    {..."TypeName": "Iban"...},
    {..."TypeName": "Bic"...},
    {..."TypeName": "SenderVatId"...},
    {..."TypeName": "ReceiverVatId"...},
    {..."TypeName": "UId"...},
    {..."TypeName": "NetTotalAmount"...},
    {..."TypeName": "VatTotalAmount"...},
    {..."TypeName": "GrandTotalAmount"...},
    {..."TypeName": "InvoiceCurrency"...},
    {..."TypeName": "DeliveryNoteId"...},
    {..."TypeName": "ReceiverOrderId"...},
    {..."TypeName": "TaxNumber"...},
    {..."TypeName": "SenderTaxId"...},
    {..."TypeName": "ReceiverTaxId"...},
    {..."TypeName": "TaxId"...},
    {..."TypeName": "Sender"...},
    {..."TypeName": "IsrReference"...},
    {..."TypeName": "IsrSubscriber"...}],
    {..."TypeName": "KId"...}],
    {..."TypeName": "CompanyRegistrationNumber"...}],
    {..."TypeName": "CostCenter"...}],
    {..."TypeName": "VatExemption"...}],
                                "PredictionGroups": <DetectionGroupResponse>[
    {
    ...,
                                "TypeName": "VatGroup",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {..."TypeName": "VatRate"...},
    {..."TypeName": "NetAmount"...},
    {..."TypeName": "VatAmount"...}]
    },
    {
    ...,
                                "TypeName": "BankGroup",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {..."TypeName": "BankCode"...},
    {..."TypeName": "BankAccount"...},
    },
    {
    ...,
                                "TypeName": "DueDateGroup",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {..."TypeName": "DueDateDate"...},
    {..."TypeName": "DueDateDuration"...},
    },
    {
    ...,
                                "TypeName": "DiscountGroup",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {..."TypeName": "DiscountDate"...},
    {..."TypeName": "DiscountDuration"...},
    {..."TypeName": "DiscountPercent"...}]
    },
    {
    ...,
                                "TypeName": "DeliveryPeriodGroup",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {..."TypeName": "DeliveryPeriodDateStart"...},
    {..."TypeName": "DeliveryPeriodDateEnd"...}]
    },
    {
    ...,
                                "TypeName": "QrCodeGroup",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {..."TypeName": "QrCodeRawString"...},
    {..."TypeName": "QrCodeDetail"...},
    },
    {
    ...,
                                "TypeName": "BoletoBarCode",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {..."TypeName": "Bar"...},
    },
    {
    ...,
                                "TypeName": "BarCode",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {..."TypeName": "Bar"...},
    },        
    {
    ...,
                                "Type": "[WhiteListGroupId]",
                                "TypeName": "[GivenDetailType]Group",
                                "InvoiceDetailTypePredictions": <DetectionResponse>[
    {...
                                "Type": "[WhiteListValueId]"
                                "TypeName": "[GivenDetailType]"
    ...},
    {...
                                "Type": "[WhiteListHintId]"
                                "TypeName": "[GivenDetailType]Hint"
    ...},
    }],
                                "LineItemTable": <LineItemTableResponse>,
                                "Sender": <ContactResponse>,
                                "Receiver": <ContactResponse>,
                                "Contacts": <List of ContactResponse>,
                                "IsQualityOk": <boolean>,
                                "ResultPdf": <string>,
                                "OcrResult": <string>,
                                "DocumentText": <string>,
                                "Confidence": <double>,
                                "InvoiceState": <integer>
    }

Paths

invoicedetail

Extracts invoice features of a provided invoice.

POST /invoicedetail/detect

Extracts invoice features of a provided invoice.

DetectInvoiceRequest

undefined

Filter

in formData

integer (int64)

Filter for Invoice details that shall be predicted
flag 'None' will return all available Invoice details for your subscription,
else define the filter by providing a bitmask for the Invoice details that shall be predicted.
e.g. Filter = GrandTotalAmount | Ibans.

Filters:

None: 0
Sender: 2
DeliveryDate: 8
GrandTotalAmount: 16
InvoiceDate: 64
Receiver: 128
InvoiceId: 1024
DocumentType: 8192
Ibans: 16384
Bics: 32768
LineItems: 65536
InvoiceCurrency: 524288
DeliveryNoteId: 1048576
CustomerId: 2097152
TaxNumber: 4194304
VatIds: 8388608
SenderOrderId: 16777216
ReceiverOrderId: 33554432
SenderOrderDate: 67108864
ReceiverOrderDate: 134217728
VatGroup: 536870912
BankGroup: 17179869184
DueDateGroup: 17592186044416
DiscountGroup: 1099511627776
IsrReference: 34359738368
IsrSubscriber: 35184372088832
KId: 70368744177664
CompanyRegistrationNumber: 140737488355328
Contacts: 281474976710656
DeliveryPeriod: 4503599627370496
CostCenter: 9007199254740992
VatExemption: 18014398509481984
TaxIds: 2305843009213693952
QRCodeGroup: 144115188075855872
BarCodeGroup: -9223372036854775808

Invoice

in formData

string

Invoice (encoded as base64 with padding string) - accepted formats: PDF, JPG, PNG, GIF, TIFF

Format

in formData

integer (int32)

Special Invoice format.
for future use only

None: 0
EbInterface: 1

PropertyStore

in formData

object

Additional properties that will be used for invoice processing, provided as Key-Value pairs.

CreateResultPdf

in formData

boolean

If this flag is set, the response will contain the sent invoice as pdf-document with marked predictions.

AddOcrResult

in formData

boolean

If this flag is set, the response will contain the OCR result as json string.

AddDocumentText

in formData

boolean

If this flag is set, the response will contain the plain text of the document as detected by the OCR.

Languages

in formData

string

This is an optional parameter to restrict the potential languages for the current document. The comma separated list will be passed to the internal OCR-Component. Specifying the correct document language (or a small potential set of languages) will reduce failures of the OCR and can improve the quality of the predictions.

in header

string application/json

Accept Header

Example Request with CURL

In the following example all invoice details are requested for a certain invoice. Therefore, a request.json file has been created. The "Filter" property is set to "None" which means that we want all possible invoice details. The "Invoice" property contains the invoice encoded in Base64.

{
                                "Filter": "None",
                                "Invoice": "YOUR_INVOICE_IN_BASE64",  
}

curl

curl -vX POST https://api.bludelta.ai/v1-18/invoicedetail/detect \
  -H 'Content-Type: application/json' \
  -H 'X-ApiKey:YOUR_API_KEY' \
  -d @request.json

200 OK

DetectInvoiceResponse

Service call successfully finished

400 Bad Request

DetectInvoiceResponse

Invoice format error

401 Unauthorized

DetectInvoiceResponse

Unauthorized. Invalid ApiKey (or invalid ApiIdentifier)

403 Forbidden

DetectInvoiceResponse

Customer is not allowed to make any predictions

500 Internal Server Error

DetectInvoiceResponse

Oops, something broke

Response Content-Types: application/json

Response Example (200 OK)


    {
                                "DocumentResolution": "integer (int32)",
                                "DocumentFormat": "string",
                                "Language": "string",
                                "InvoiceDetailTypePredictions": "List",
                                "PredictionGroups": "List",
                                "FormattedResult": "string",
                                "IsQualityOk": "boolean",
                                "ResultPdf": "string",
                                "OcrResult": "string",
                                "DocumentText": "string"
    }

The maximum time to process a document is 230 seconds. If a request cannot be processed within that time, for example due to too many pages with lots of text, a timeout will happen (Http status 502 or 504).
Many HttpClients set a timeout of 100 seconds by default. After this period, the client will close the request and receive an error (Http status 499). So it is highly recommended to configure a client timeout of 230+ seconds.
If a client receives a timeout (Http 499 | 502 | 504), it makes sense to wait 15 minutes and then retry processing the document. CAUTION: You should not retry more often than 3 times!

Schema Definitions

Object: object

Object

DetectInvoiceRequest: object

Extracts invoice features of a provided invoice.
Input: Base64 encoded.
Supported file formats: pdf, jpg, png, tif (also multi page), gif, bmp, ico
Recommended max image dimensions per page: 8400x8400 in all formats (including pdf).

Filter: integer (int64)

None: 0
Sender: 2
DeliveryDate: 8
GrandTotalAmount: 16
InvoiceDate: 64
Receiver: 128
InvoiceId: 1024
DocumentType: 8192
Ibans: 16384
Bics: 32768
LineItems: 65536
InvoiceCurrency: 524288
DeliveryNoteId: 1048576
CustomerId: 2097152
TaxNumber: 4194304
VatIds: 8388608
SenderOrderId: 16777216
ReceiverOrderId: 33554432
SenderOrderDate: 67108864
ReceiverOrderDate: 134217728
VatGroup: 536870912
BankGroup: 17179869184
DueDateGroup: 17592186044416
DiscountGroup: 1099511627776
IsrReference: 34359738368
IsrSubscriber: 35184372088832
KId: 70368744177664
CompanyRegistrationNumber: 140737488355328
Contacts: 281474976710656
DeliveryPeriod: 4503599627370496
CostCenter: 9007199254740992
VatExemption: 18014398509481984
TaxIds: 2305843009213693952
QRCodeGroup: 144115188075855872
BarCodeGroup: -9223372036854775808

Invoice: string

Invoice (encoded as base64 with padding string) - accepted formats: PDF, JPG, PNG, GIF, TIFF

Format: integer (int32)

Special Invoice format.
for future use only

None: 0
EbInterface: 1

PropertyStore: Dictionary<String,String>

Additional properties that will be used for invoice processing, provided as Key-Value pairs.

CreateResultPdf: boolean

If this flag is set, the response will contain the sent invoice as pdf-document with marked predictions.

AddOcrResult: boolean

If this flag is set, the response will contain the OCR result as json string.

AddDocumentText: boolean

If this flag is set, the response will contain the plain text of the document as detected by the OCR.

Languages: string

de...German
en...English
es...Spanish
pl...Polish
it...Italian
fr...French
cs...Czech
sk...Slovakian
nl...Dutch
nb...Norwegian
hr...Croatian
tr...Turkish
pt...Portuguese
sv...Swedish
da...Danish
sl...Slovenian

Example

{
                                "Filter": "integer (int64)",
                                "Invoice": "string",
                                "Format": "integer (int32)",
                                "PropertyStore": "object",
                                "CreateResultPdf": "boolean",
                                "AddOcrResult": "boolean"
                                "AddDocumentText": "boolean"
                                "Languages": "string"
}

Dictionary<String,String>: object

Dictionary<String,String>

Key: "ReceiverVatId" string Value: receiver vat id(s) string: The given receiver Vat id (single id or comma separated list) is used by the service to identify receiver Vat ids. Whenever an extracted Vat id is found in the list, it will be returned as receiver Vat id. The name of the result is set to ReceiverVatId.
Key: "SenderVatId" string Value: sender vat id(s) string: The given sender Vat id (single id or comma separated list) is used by the service to identify sender Vat ids. Whenever an extracted Vat id is found in the list, it will be returned as sender Vat id. The name of the result is set to SenderVatId.
Key: "DocumentReceiverCountry" string Value: Country of document receiver string (ISO 3166-1 Alpha 2): The given receiver country is used for all kinds of country dependent information, like VatId or Currency.
Key: "DocumentReceivedDate" string Value: Date when document was received string (YYYY-MM-DD / ISO 8601): The date when the document was received might be used for validation purposes in the future.
Key: "SessionLogId" string Value: session id string: The session id is used to add this id to every log entry belonging to this request for easy log file monitoring.

Example

"object"

DetectInvoiceResponse: object

DetectInvoiceResponse

DocumentResolution: integer (int32)

Resolution of the original document in dpi.

DocumentFormat: string

The format of the document which is either "Letter" or "Receipt"

Language: string

The language of the document that was identified by BLU DELTA

InvoiceDetailTypePredictions: DetectionResponse

List of Predictions - One for each predicted invoice detail.

PredictionGroups: DetectionGroupResponse

List of PredictionGroups - One for each predicted invoice detail
e.g. VatGroup, containing predictions for Vat Rate, Net Amount and Vat Amount

Sender: ContactResponse

The sender (biller) of the invoice

Receiver: ContactResponse

The receiver of the invoice

Contacts: List of ContactResponse

For German documents, the list contains all contacts found on the document - including sender and receiver. For all other languages, the list contains only sender and receiver.

LineItemTable: LineItemTableResponse

Table of line items

FormattedResult: string

Special invoice format. (for future use only)

IsQualityOk: boolean

Invoice quality flag. (for future use only)

ResultPdf: string

Result pdf-document with marked predictions (encoded as base64 string).
Will contain an empty string if the pdf could not be created successfully.

OcrResult: OCR Result Schema Definitions

OCR Result (as json string).
Will contain an empty string if the OCR result could not be created successfully.

DocumentText: string

Plain text of the document as detected by the OCR.
Will contain an empty string if the OCR failed.
The escape sequence \r\n (CarriageReturn + LineFeed) is used to signify the end of a line.

Confidence: double

Describes the confidence that the invoice can be auto-processed without human validation.
(-1 = unknown, 0 = validate manually, 1 = autoprocess)

InvoiceState: integer (int32)

Specifies if the response contains all requested data.
The value is built from a bitmask for all tasks which could not successfully
deliver a result.

States:

Ok: 0
Prediction failed: 1
Result pdf failed: 2
OCR Result failed: 4

Example: The value 3 means that both, the prediction and the result pdf generation, failed.

Example


    {
                                "DocumentResolution": "integer (int32)",
                                "DocumentFormat": "string",
                                "Language": "string",
                                "InvoiceDetailTypePredictions": "List",
                                "PredictionGroups": "List",
                                "Sender": "ContactResponse",
                                "Receiver": "ContactResponse",
                                "Contacts": "List of ContactResponse",
                                "LineItemTable": "LineItemTableResponse",
                                "FormattedResult": "string",
                                "IsQualityOk": "boolean",
                                "ResultPdf": "string",
                                "OcrResult": "string",
                                "DocumentText": "string",
                                "Confidence": "double",
                                "InvoiceState": "integer (int32)"
    }

DetectionResponse: object

DetectionResponse

Type: integer (int64)

Predicted invoice detail
The definition of the actual type values can be found here.

TypeName: string

Name of predicted invoice detail
The definition of the actual name values can be found here.

Note: if specific sender or receiver vat-ids are detected, then vat-id name
values will be overwritten with more specific name values. These values are
listed here:

SenderVatId (if the VatId belongs to the sender) or
ReceiverVatId (if the VatId belongs to the receiver) or
VatId (for others)

The same is valid for sender or receiver tax-ids:

SenderTaxId (if the TaxId belongs to the sender) or
ReceiverTaxId (if the TaxId belongs to the receiver) or
TaxId (for others)

Value: string

Predicted value

Formats:

GrandTotalAmount: decimal separator '.', no group separator, two decimal digits, e.g. 9.00, 2314.50, -12.99
NetAmount: decimal separator '.', no group separator, two decimal digits, e.g. 9.00, 2314.50, -12.99
VatAmount: decimal separator '.', no group separator, two decimal digits, e.g. 9.00, 2314.50, -12.99
VatRate: decimal separator '.', no group separator, one decimal digits, e.g. 20.0, 19.0, 10.0
InvoiceDate: YYYY-MM-DD (ISO 8601)
DeliveryDate: YYYY-MM-DD (ISO 8601)
SenderOrderDate: YYYY-MM-DD (ISO 8601)
ReceiverOrderDate: YYYY-MM-DD (ISO 8601)
InvoiceId: string
InvoiceCurrency: string
CustomerId: string
SenderOrderId: string
ReceiverOrderId: string
DocumentType: 'Invoice', 'CreditMemo' or 'Other'
Ibans: string without blanks, comma separated
Bics: string without blanks, comma separated
VatIds: string without blanks, comma separated
DeliveryNoteId: string
Sender: string
TaxNumber: string
BankCode: string
BankAccount: string
DueDateDate: YYYY-MM-DD (ISO 8601)
DueDateDuration: number (days)
DiscountDate: YYYY-MM-DD (ISO 8601)
DiscountDuration: number (days)
DiscountPercent: decimal separator '.', no group separator,
IsrReference: digits
IsrSubscriber: digits
KId: digits
CompanyRegistrationNumber: string
DeliveryPeriodDateStart: YYYY-MM-DD (ISO 8601)
DeliveryPeriodDateEnd: YYYY-MM-DD (ISO 8601)
CostCenter: string
VatExemption: 'Vat Exemption' or empty string
TaxIds: string without blanks, comma separated
LineItem.PositionId: string
LineItem.ItemId: string
LineItem.Description: string
LineItem.OrderId: string
LineItem.DeliveryId: string
LineItem.DeliveryDate: YYYY-MM-DD (ISO 8601)
LineItem.Quantity: decimal separator '.', no group separator, at least one decimal digits, e.g. 1.0, 1.55, 1.123
LineItem.Unit: string
LineItem.VatRate: decimal separator '.', no group separator, one decimal digits, e.g. 20.0, 19.0, 10.0
LineItem.UnitPrice: decimal separator '.', no group separator, four decimal digits, e.g. 1.0000, 0.0001, 0.0050
LineItem.VatRate: decimal separator '.', no group separator, one decimal digits, e.g. 20.0, 19.0, 10.0
LineItem.Discount: string
LineItem.TotalAmount: decimal separator '.', no group separator,two decimal digits, e.g. 9.00, 2314.50, 12.03
BarCodeGroup.CodeDetail: string, digits only

Score: double (double)

Scored probability. Value between zero and one. Rounded to 4 decimal places.

RecommendedThreshold: double (double)

"Recommendation to use this detail only if 'Score' is higher or equal to this threshold. Threshold calculation based on benchmark on a custom document set or default set. Value between zero and one. If minus one, then no recommendation."

X: integer (int32)

X-Position of prediction according to the document resolution

Y: integer (int32)

Y-Position of prediction according to the document resolution

Width: integer (int32)

Width of prediction according to the document resolution

Height: integer (int32)

Height of prediction according to the document resolution

Confidence: double (double)

Describes the confidence that this invoice detail can be auto-processed without human validation.
(-1 = unknown, 0 = validate manually, 1 = autoprocess)

Example

{
                                "Type": "int (int64)",
                                "TypeName": "string",
                                "Value": "string",
                                "Score": "double (double)",
                                "X": "integer (int32)",
                                "Y": "integer (int32)",
                                "Width": "integer (int32)",
                                "Height": "integer (int32)",
                                "Confidence": "double (double)"
}

DetectionGroupResponse: object

DetectionGroupResponse

Type: integer (int64): Predicted invoice detail
TypeName: string: Predicted invoice detail
InvoiceDetailTypePredictions: DetectionResponse: List of Predictions - One for each predicted invoice detail.

Example

{
                                "Type": "int (int64)",
                                "TypeName": "string",
                                "InvoiceDetailTypePredictions": "List"
}

ContactResponse: object

ContactResponse

Name: DetailResponse: Name of the contact
Address: AddressResponse: Address of the contact
Score: double (double): Scored probability. Value between zero and one. Rounded to 4 decimal places.
RecommendedThreshold: double (double): "Recommendation to use this detail only if 'Score' is higher or equal to this threshold. Threshold calculation based on benchmark on a custom document set or default set. Value between zero and one. If minus one, then no recommendation."
WebsiteUrl: DetailResponse: List of websites of the contact
Email: DetailResponse: List of e-mail addresses of the contact
Phone: DetailResponse: Phone number of the contact
Fax: DetailResponse: Fax number of the contact

Example

{
                                "Name": "DetailResponse",
                                "Address": "AddressResponse",
                                "Score": "double (double)",
                                "WebsiteUrl": "List",
                                "Email": "List",
                                "Phone": "DetailResponse",
                                "Fax": "DetailResponse"
}

AddressResponse: object

AddressResponse

Street: DetailResponse: Street (incl. street number)
ZipCode: DetailResponse: Zip code / postal code
City: DetailResponse: City
Country: DetailResponse: Country (ISO 3166-1)
X: integer (int32): X-Position according to the document resolution
Y: integer (int32): Y-Position according to the document resolution
Width: integer (int32): Width according to the document resolution
Height: integer (int32): Height according to the document resolution

Example

{
                                "Street": "DetailResponse",
                                "ZipCode": "DetailResponse",
                                "City": "DetailResponse",
                                "Country": "DetailResponse",
                                "X": "integer (int32)",
                                "Y": "integer (int32)",
                                "Width": "integer (int32)",
                                "Height": "integer (int32)"
}

LineItemTableResponse: object

LineItemTableResponse

LineItems: LineItemResponse: List of predicted line items
LineItemResponse

Example

{
                                "LineItems": "List"
}

LineItemResponse: object

LineItemResponse

PositionNumber: integer (int32): Sequential number for each predicted line item, starting at 1
PositionId: DetailResponse: Position identifier: string
ItemId: DetailResponse: Idendifier of article number: string
Description: DetailResponse: Description: string
OrderId: DetailResponse: Order identifier: string
DeliveryId: DetailResponse: Delivery identifier: string
DeliveryDate: DetailResponse: Delivery date: YYYY-MM-DD (ISO 8601)
Quantity: DetailResponse: Quantity: decimal separator '.', no group separator, at least one decimal digits, e.g. 1.0, 1.55, 1.123
Unit: DetailResponse: Unit: string
UnitPrice: DetailResponse: Unit price: decimal separator '.', no group separator, four decimal digits, e.g. 1.0000, 0.0001, 0.0050
VatRate: DetailResponse: Vat rate: decimal separator '.', no group separator, one decimal digits, e.g. 20.0, 19.0, 10.0
Discount: DetailResponse: Discount: string
TotalAmount: DetailResponse: TotalAmount: decimal separator '.', no group separator,two decimal digits, e.g. 9.00, 2314.50, 12.03
Score: double (double): Scored probability. Value between zero and one. Rounded to 4 decimal places.
RecommendedThreshold: double (double): "Recommendation to use this detail only if 'Score' is higher or equal to this threshold. Threshold calculation based on benchmark on a custom document set or default set. Value between zero and one. If minus one, then no recommendation."
X: integer (int32): X-Position of prediction according to the document resolution
Y: integer (int32): Y-Position of prediction according to the document resolution
Width: integer (int32): Width of prediction according to the document resolution
Height: integer (int32): Height of prediction according to the document resolution

Example


    {
                                "PositionNumber": "integer (int32)",
                                "PositionId": "DetailResponse",
                                "ItemId": "DetailResponse",
                                "Description": "DetailResponse",
                                "OrderId": "DetailResponse",
                                "DeliveryId": "DetailResponse",
                                "DeliveryDate": "DetailResponse",
                                "Quantity": "DetailResponse",
                                "Unit": "DetailResponse",
                                "UnitPrice": "DetailResponse",
                                "VatRate": "DetailResponse",    
                                "Discount": "DetailResponse",
                                "TotalAmount": "DetailResponse",
                                "Score": "double (double)",
                                "X": "integer (int32)",
                                "Y": "integer (int32)",
                                "Width": "integer (int32)",
                                "Height": "integer (int32)"
    }

DetailResponse: object

DetailResponse

Name: string: Name of predicted detail
Text: string: Original text as detected on the document
Empty: if no related text was detected or this detail is derived from context and not one explicit text position (e.g. DocumentType or InvoiceCurrency).
Value: string: Normalized value derived from original text
Empty: No reliable value detected or in case request prop set “ForceReturnBestMatch=true” it means no candidate found at all.
Score: double (double): Scored probability. Value between zero and one. Rounded to 4 decimal places.
RecommendedThreshold: double (double): "Recommendation to use this detail only if 'Score' is higher or equal to this threshold. Threshold calculation based on benchmark on a custom document set or default set. Value between zero and one. If minus one, then no recommendation."
X: integer (int32): X-Position of prediction according to the document resolution
Y: integer (int32): Y-Position of prediction according to the document resolution
Width: integer (int32): Width of prediction according to the document resolution
Height: integer (int32): Height of prediction according to the document resolution

Example

{
                                "Name": "string",
                                "Text": "string",
                                "Value": "string",
                                "Score": "double (double)",
                                "X": "integer (int32)",
                                "Y": "integer (int32)",
                                "Width": "integer (int32)",
                                "Height": "integer (int32)"
}

EInvoiceResponse: object

Contains information about EInvoice and list of document binaries related to it.

DocumentBinaries: DocumentBinary: A list of binaries representing different documents.

Version: string: Version like XRechnung 3.0; ZUGFeRD Facture-X, EN 16931 (Comfort); etc.

Type: string: Supported types: UBL, CII or CII Hybrid

ValidationStatus: string: Supported status: Ok, Warning or Error

Example


    {
                                "DocumentBinaries": 
                                [   
                                    {
                                        "ContentType": "PDFOriginal",
                                        "MediaType": "application/pdf",
                                        "Embedding": "A_DOCUMENT_IN_BASE64_FORMAT"
                                        "FileName": "FILE_NAME"
                                        "Name": "NAME"
                                    } 
                                ],
                                "Version": "VERSION",
                                "Type": "TYPE",
                                "ValidationStatus": "STATUS"
    }

DocumentBinary: object

Represents a document in binary format, including metadata.

ContentType: string: "PDFOriginal" is used when a ZUGFeRD PDF is uploaded. It contains the embedded XInvoice XML. "PDFGenerated" applies when an XInvoice XML file is uploaded and a PDF is generated from it. "PDFGenerated" is also used for the validation protocol. "Original" is used for the attachments.
MediaType: string: Supported media types: "application/pdf", "image/jpeg", "image/png", "text/csv", "application/vnd.oasis.opendocument.spreadsheet", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet".
Embedding: string: The binary data of the document encoded in Base64.
FileName: string: The file name of document.
Name: string: Name of document.

Example


    {
                                "ContentType": "PDFOriginal|PDFGenerated|Original",
                                "MediaType": "application/pdf",
                                "Embedding": "A_DOCUMENT_IN_BASE64_FORMAT"
                                "FileName": "FILE_NAME"
                                "Name": "NAME"

    }

Documentation by Spectacle

V1.18

Invoice and Document Capturing API Reference API Reference

API Endpoint

Request Content-Types: application/json

Request Custom Header

X-ApiKey: YOUR_API_KEY

X-ApiIdentifier: YOUR_API_IDENTIFIER (optional)

Attention: Depending on the configuration of your API key, you may have to send a predefined identifier here.

Response Content-Types: application/json

Schemes: http, https

Version: 1.18.x

API Json Response (exemplary)

Paths

Extracts invoice features of a provided invoice.

Example Request with CURL

In the following example all invoice details are requested for a certain invoice. Therefore, a request.json file has been created. The "Filter" property is set to "None" which means that we want all possible invoice details. The "Invoice" property contains the invoice encoded in Base64.

curl

Response Content-Types: application/json

Response Example (200 OK)

Schema Definitions

Object: object

DetectInvoiceRequest: object

Example

Dictionary<String,String>: object

Example

DetectInvoiceResponse: object

Example

DetectionResponse: object

Example

DetectionGroupResponse: object

Example

ContactResponse: object

Example

AddressResponse: object

Example

LineItemTableResponse: object

Example

LineItemResponse: object

Example

DetailResponse: object

Example

EInvoiceResponse: object

Example

DocumentBinary: object

Example