The Entity Extraction API offers an asynchronous API for Entity Extraction from invoice and contract documents using two REST interfaces for document upload and result polling
Used to upload your document for entity extraction. Document data can be uploaded either as file or OCR data, e.g., from previous OCR. The response includes a job id which is used to poll for results using REST interface /entities/
customer-id: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
x‑api-key: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
2.2.Request Parameter
The request body includes the following list of form parameters:
document : file containing your document; documents must be limited to a file size of 4 MB; entity extraction is limited to the first 10 pages of the document
supported file types: pdf (single and multi page), tiff (single page and multi page, supported compressions: none, adobe_deflate, ccitt group 3 or 4, lzw) and jpg
required: yes, excludes usage of parameters “text” and “hocr”
Usage of parameters “document” and “text”/“hocr” do exclude each other!
text : OCR text of your document, e.g., resulting from previous OCR
required: yes, requires usage of parameter “hocr” and excludes usage of parameter “document”
hocr : hOCR data of your document, e.g., resulting from previous OCR
required yes, requires usage of parameter “text” and excludes usage of parameter “document”
Usage of parameters “text” and “hocr” will skip the OCR step of the Entity Extraction API and, hence, significantly improve the request performance!
language : language used for character recognition (OCR)
supported values: [ ”en” | ”de” | ”en+de”]
required: no
default: “en+de”
documentClass : domain of your document; determines the entity types extracted by the Entity Extraction API
supported values: [ ”invoice” | ”contract” ]
required: no
default: determined automatically
useEmbeddedText : use embedded document text to skip OCR step and, hence, improve request performance; only applicable for pdf files when using parameter “document”
supported values: [ “true” | “false” ]
required: no
default: “false”
getHocr : return the document’s content in hOCR format (in addition to plain text)
supported values: [ ”true” | ”false” ]
required: no
default: “false”
uploadId : required for processing document files > 4 MB: upload id returned from endpoint GET /uploadurl; each upload id must only be used once
required: no
callbackUrl : callback URL to which the Entity Extraction API sends a HTTP POST request after document processing is finished; the callback request includes a job-id which can be used to call GET /entities/ for the extraction results
required: no
Example Callback
POST
headers {"content-type": application/json"}
body {"jobId": "229cdae0162805414755d5ee7eed216bc975738c"}
2.3.Response HTTP Status
200: Document uploaded successfully.
400: Bad request. Missing or invalid input parameter.
401: Authorization failed. Operation not allowed.
403: Authorization failed due to invalid credentials.
415: Unsupported file format.
429: Too many requests. The overall number of requests to all REST endpoints of the Entity Extraction API must not exceed 100 requests/s for each customer.
2.4.Response Header
content-type: HTTP content type
supported values: “application /json”
2.5.Response Body
jobId: Job id used for polling the resulting entities from REST interface /entities
type: String
uploadFile: Description of the uploaded file
type: Map
object properties:
name: "size" type: Integer
name: "mime"
type: String
name: "name"
type: String
2.6.Example
Request
POST /document
headers {"x-api-key": , "customer-id": }
body {"document": }
Used to poll for results from processing of the uploaded document using the job id from REST interface POST /document response.
The response includes the resulting entities which are organised in ungrouped and grouped entities depending on the entity type:
Ungrouped entities (field ‘entities’) consist of an entity name and a list of 0..n entity values which are sorted according to decreasing probability, i.e., the first value is the most likely result.
Each entity value includes the following attributes:
originalValue: OCR value that was read from the document
value: normalized value for specific entity types, e.g., for currency, ‘€’ is replaced by ‘EUR’
confidence: float value between 0..1 which denotes the probability that an entity value is valid, i.e., the Entity Extraction API proposes potentially multiple values for each entity type which might include valid and invalid values
verified: boolean flag which denotes that an entity value is valid with respect to a dedicated set of high-level validation rules that are applied by the Entity Extraction API to each entity type, e.g., invoice amounts must be parsable to floating point values
Grouped entities (field ‘groups’) consist of a group name and an unsorted list of 0..n group entities.Currently supported group types:
taxRates: includes entities ‘invoice_taxRateGroup_taxRate’, ‘invoice_taxRateGroup_taxAmount’‚ and ‘invoice_taxRateGroup_netAmount’
items: includes entities ‘item_group_quantity’, ‘item_group_singleNetAmount’ and ‘item_group_totalNetAmount
Each group entity includes the following attributes:
members: a tuple of entity values (see above) that are related to each other; each group type is assigned to a static set of entity types; in a particular group entity, each entity type can be included exactly once or can be missing due to suboptimal extraction results
verified: boolean flag which denotes that a group entity is consistent with respect to a dedicated set of high-level validation rules that are applied by the Entity Extraction API to each group type, e.g., ‘taxRate’ * ’netAmount’ = ‘taxAmount’
3.1.Request Header
content-type: HTTP content type
supported values: “application/json“
required: yes
customer-id: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
x‑api-key: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
3.2.Path Variable
JOB_ID : the job id is received from the response of the call to REST interface /document
3.3.Response HTTP Status
200: Entity extraction successful.
202: Job processing not finished yet.
204: No entities found.
400: Bad request. Missing or invalid input parameter.
401: Authorization failed. Operation not allowed.
403: Authorization failed due to invalid credentials.
422: File cannot be processed.
429: Too many requests. The overall number of requests to all REST endpoints of the Entity Extraction API must not exceed 100 requests/s for each customer.
customer-id: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
x‑api-key: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
4.2.Request Parameter
The request body includes a single body parameter that includes the following fields in JSON format:
jobIds : list of job ids received from calling POST /document
type: list
required: yes
4.3.Response HTTP Status
200: Query finished successfully.
400: Bad request. Missing or invalid input parameter.
401: Authorization failed. Operation not allowed.
403: Authorization failed due to invalid credentials.
429: Too many requests. The overall number of requests to all REST endpoints of the Entity Extraction API must not exceed 100 requests/s for each customer.
4.4.Response Header
content-type: HTTP content type
supported values: “application /json”
4.5.Response Body
jobs: map containing job ids from request as keys and job states as values
Used to request a URL for the upload of large document files (> 4 MB). After uploading your document you must use endpoint POST /document to start document processing.
5.1.Request Header
content-type: HTTP content type
supported values: “application/json“
required: yes
customer-id: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
x‑api-key: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
5.2.Response HTTP Status
200: Successfully generated upload URL
401: Authorization failed. Operation not allowed.
403: Authorization failed due to invalid credentials.
5.3.Response Header
content-type: HTTP content type
supported values: “application /json”
5.4.Response Body
uploadUrl: URL for uploading your document file using HTTP REST. Each URL must only be used once.
uploadId: upload id that must be passed as parameter ‘uploadId’ in POST /document endpoint for processing your uploaded document file
5.5.Example
Request
GET /uploadurl
headers {"x-api-key": , "customer-id": }
customer-id: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
x‑api-key: part of your credentials which you receive upon registration for the Entity Extraction API
required: yes
6.2.Request Parameter
The request body includes a single body parameter that includes the following fields in JSON format:
documentClass : document class id of training document
required : yes
supported values : [ “INVOICE” | “CONTRACT” ]
language : language id of the training document
required : yes
supported values : [ “en” | “de” ]
text : plain text from training document
required: yes
document : document file
supported file types: [ pdf | tiff | jpg ]
required: no
Usage of parameters “document” requires content-type “multipart/form-data”. If parameter “document” is omitted the content-type must be “application/json”.
entities : entities from training document
required : yes
Must only include supported entities for your document class. Entities may be omitted or may include empty values (i.e., empty array). Each entity must contain a single attribute ‘value’ that contains the training value as String parameter.
6.3.Response HTTP Status
200: Successfully submitted train data.
204: Train data empty.
400: Bad request. Missing or invalid input parameter.
401: Authorization failed. Operation not allowed.
403: Authorization failed due to invalid credentials.
429: Too many requests. The overall number of requests to all REST endpoints of the Entity Extraction API must not exceed 100 requests/s for each customer.
For invoice documents, the Entity Extraction API provides a default set of entities that are extracted. The Buildsimple team may add additional entities to the default entity set for invoice documents in future releases.
7.1.1.Invoice
The following entities are located at field ‚entities‘ of the response from GET /entities/
Entity name
Description
invoice_invoiceDate
invoice date
invoice_invoiceNumber
invoice number
invoice_orderNumber
order number
invoice_deliveryDate
delivery date
invoice_invoiceCurrency
invoice currency
invoice_invoiceGrossAmount
invoice gross amount
invoice_dueDate
due date
invoice_deliveryNumber
delivery number
7.1.2.Vendor
The following entities are located at field ‚entities‘ of the response from GET /entities/
Entity name
Description
vendor_name
vendor name
vendor_street
vendor street name and house number
vendor_zip
vendor zip code
vendor_city
vendor city
vendor_bankName
name of the vendor’s bank
vendor_iban
vendor IBAN
vendor_bic
vendor BIC
vendor_taxIdNumber
vendor tax id
vendor_vatNumber
vendor VAT number/td>
7.1.3.Recipent
The following entities are located at field ‚entities‘ of the response from GET /entities/
Entity name
Description
recipient_company
name of the recipient’s company
recipient_street
recipient street and house number
recipient_zip
recipient zip code
recipient_city
recipient city
7.1.4.Invoice Items
The following entities are located at field ‚members‘ within list ‚groups[‚items‘]‘ of the response from GET /entities/.Groups may be incomplete, i.e., contain only 1–5 entities.
Entity name
Description
item_group_quantity
quantity of an invoice item (grouped by invoice item)
item_group_singleNetAmount
single net amount (grouped by invoice item)
item_group_totalNetAmount
total net amount (grouped by invoice item)
item_group_description
description of invoice item (grouped by invoice item)
item_group_materialNumber
material number (grouped by invoice item)
item_group_taxRate
tax rate applied to invoice item (grouped by invoice item)
7.1.5.Tax Rates
The following entities are located at field ‚members‘ within list ‚groups[‚taxRates‘]‘ of the response from GET /entities/. Groups may be incomplete, i.e., contain only 1–2 entities.
Entity name
Description
invoice_taxRateGroup_taxRate
tax rate
invoice_taxRateGroup_netAmount
total net amount (grouped by tax rate)
invoice_taxRateGroup_taxAmount
total tax amount (grouped by tax rate)
7.2.Contract Entities
For contract documents, the Entity Extraction API provides a default set of entities that are extracted. The Buildsimple team may add additional entities to the default entity set for invoice documents in future releases.
7.2.1.Contractor
The following entities are located at field ‚entities‚ of the response from GET /entities/
Entity name
Description
contractor_name
contractor name
contractor_street
contractor street and house number
contractor_zip
contractor zip code
contractor_city
contractor city
contractor_contact
contact person on contractor side
7.2.2.Contractee
The following entities are located at field ‚entities‚ of the response from GET /entities/
Entity name
Description
contractor_name
contractor name
contractor_street
contractor street and house number
contractor_zip
contractor zip code
contractor_city
contractor city
contractor_contact
contact person on contractor side
7.2.3.Contract
The following entities are located at field ‚entities‚ of the response from GET /entities/
