Entity reference

amount

Describes an amount of money with a specific currency in the format <Amount>:<Currency Code>, where <Amount> is a decimal number with ”.” as decimal separator and ”:” as delimiter between <Amount> and <Currency Code>.

The currency code must be given according to the list specified in ISO 4217.

Format

Name Type Description
entity string Must be amount
value string Amount in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "amount",
    "value": "33.78:EUR",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Valid Feedback

Form Example
<Number>:<Currency Code/Symbol> 12.3:EUR; 12,4:USD; 12.98:USD
<Number> <Currency Code/Symbol> (1-space-separation) 12,3 EUR; 12,4 USD; 12 €
<Currency Code/Symbol> <Number> (1-space-separation) EUR 12.3; $ 12.4
  • If there is no <Number> in the string, it will be rejected.
  • If there is no <Currency Code/Symbol>, it will be treated as default ‘EUR’ (default currency code).

bankaccount

Describes a bank account number.

Format

Name Type Description
entity string Must be bankaccount
value string Bank account number in the normalized form (without spaces between digits)
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "bankaccount",
    "value": "1597880",
    "box": {
        "page": 1,
        "left": 506.0,
        "top": 777.0,
        "width": 53.0,
        "height": 6.0
    }
}

Valid Feedback

Form Example
Digits 1597880

If the string has less than 3 digits, it will be rejected.

banknumber

Describes a bank number.

Format

Name Type Description
entity string Must be banknumber
value string Bank number in the normalized form (without spaces between digits)
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "banknumber",
    "value": "70250150",
    "box": {
        "page": 1,
        "left": 147.0,
        "top": 427.0,
        "width": 52.0,
        "height": 8.0
    }
}

Valid Feedback

Form Example
8 digits 70250150

bic

Describes a BIC number.

Format

Name Type Description
entity string Must be bic
value string BIC number in the normalized form (without spaces between digits and letters)
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "bic",
    "value": "GENODEF1HH2",
    "box": {
        "page": 1,
        "left": 506.0,
        "top": 777.0,
        "width": 53.0,
        "height": 6.0
    }
}

Valid Feedback

Form Example
String matching BIC format GENODEF1HH2

city

Describes a sender city.

Format

Name Type Description
entity string Must be city
value string The city name
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "city",
    "value": "München",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

companyname

Describes a (sender) company name.

Format

Name Type Description
entity string Must be companyname
value string The company name
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "companyname",
    "value": "Weinquelle Lühmann",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Valid Feedback

Form Example
Random string with at least 2 letter/digit characters O2, BMW, ABC GmbH

A string with single letter/digit character will be rejected.

companynameaddition

Describes a (sender) company name addition (e.g. Kundenservice).

Format

Name Type Description
entity string Must be companynameaddition
value string The company name addition
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "companynameaddition",
    "value": "Kundenservice",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

companyregisterid

Describes a German Register number in the format <Area of the Commercial Registry>:<Number>:<Office of the Registry> with ”:” as delimiter between components.

Format

Name Type Description
entity string Must be companyregisterid
value string Register number in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "companyregisterid",
    "value": "HRB:108514:München",
    "box": {
        "page": 1,
        "left": 525.0,
        "top": 805.0,
        "width": 34.0,
        "height": 6.0
    }
}

currency

Describes the currency of the document.

The currency code must be given according to the list specified in ISO 4217.

Format

Name Type Description
entity string Must be currency
value string Currency in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "currency",
    "value": "EUR",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Valid Feedback

Form Example
Euro currency symbol
Euro Currency name/code EUR, EURO

Since only German documents are supported at the moment, the following string are allowed: €, EUR, EURO

customerid

Describes a customer ID.

Format

Name Type Description
entity string Must be customerid
value string Customer ID in the normalized form (without spaces between digits and letters)
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "customerid",
    "value": "M500721563",
    "box": {
        "page": 1,
        "left": 317.0,
        "top": 123.0,
        "width": 158.0,
        "height": 8.0
    }
}

Valid Feedback

Form Example
A string with length >= 1 and at least 1 digit 12345, KD678

date

Describes a date in the format <Year>-<Month>-<Day> with “-” as delimiter between date components.

Format

Name Type Description
entity string Must be date
value string Date in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "date",
    "value": "2012-11-16",
    "box": {
        "page": 1,
        "left": 429.0,
        "top": 143.0,
        "width": 40.0,
        "height": 8.0
    }
}

Valid Feedback

Form Example
yyyy-mm-dd 2015-10-05
German style date 05.10.2015, 05-10-2015, 05 Okt 2015, 05 Oktober 2015

doctype

Describes a document type as one of the following values:

  • BankStatement
  • Contract
  • Invoice
  • Reminder
  • RemittanceSlip
  • TravelExpenseReport
  • Other

Note

This table reflects the current state of document types in the Gini API. New document types can be added in the future without necessarily changing the API’s version number.

There are also some other document types that are part of the incubator API. See the documentation about the incubator API for more details.

Format

Name Type Description
entity string Must be doctype
value string The document type

Example

{
    "entity": "doctype",
    "value": "Invoice"
}

Valid Feedback

Form Example
One of the above listed values Invoice, Reminder

documentdomain

Describes a document domain as one of the following values:

  • TeleCommunication
  • Other
  • HealthInsurance
  • Energy
  • Travel

Format

Name Type Description
entity string Must be documentdomain
value string The document domain

Example

{
    "entity": "documentdomain",
    "value": "TeleCommunication"
}

Valid Feedback

Form Example
One of the above listed values Travel, HealthInsurance

email

Describes an email in the format <Name>@<Domain> with “@” as a delimiter between email components.

Format

Name Type Description
entity string Must be email
value string Email in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "email",
    "value": "info@t-online.de",
    "box": {
        "page": 1,
        "left": 189.0,
        "top": 820.0,
        "width": 73.0,
        "height": 7.0
    }
}

Valid Feedback

Form Example
Valid email address hello@gini.net

iban

Describes an IBAN.

Format

Name Type Description
entity string Must be iban
value string IBAN in the normalized form (without spaces between digits and letters)
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "iban",
    "value": "DE74700500000000028273",
    "box": {
        "page": 1,
        "left": 425.0,
        "top": 770.0,
        "width": 83.0,
        "height": 6.0
    }
}

Valid Feedback

Form Example
Valid IBAN DE68700202700667302269

Invalid IBAN will be rejected.

invoiceid

Describes an invoice ID as identifier.

Format

Name Type Description
entity string Must be invoiceId
value string Invoice ID in the normalized form (without spaces between digits and letters)
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "invoiceid",
    "value": "201210124056",
    "box": {
        "page": 1,
        "left": 429.0,
        "top": 133.0,
        "width": 53.0,
        "height": 8.0
    }
}

Valid Feedback

Form Example
A string with length >= 1 and at least 1 digit 12345, RE 67890

paymentstate

Describes a payment state as one of the following values:

  • Paid
  • ToBePaid

Format

Name Type Description
entity string Must be paymentState
value string The payment state

Example

{
    "entity": "paymentState",
    "value": "Paid"
}

Valid Feedback

Form Example
One of the above listed values Paid, ToBePaid

phonenumber

Describes a phone number in one of two formats <CountryCode> <Number> with ” ” as a delimiter and <Number> without a country code. All punctuation marks (e.g. “/”, “-”), spaces and “(0)” (e.g. +49(0)61957746361) are deleted.

Format

Name Type Description
entity string Must be phonenumber
value string The phone number in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "phonenumber",
    "value": "08923508270",
    "box": {
        "page": 1,
        "left": 425.0,
        "top": 770.0,
        "width": 83.0,
        "height": 6.0
    }
}

Valid Feedback

Form Example
Phonenumber-like string +49 89 1234 567

Brackets, spaces, leading ‘+’, and ‘-‘ are allowed.

poboxnumber

Describes a post-office box of sender.

Format

Name Type Description
entity string Must be poboxnumber
value string The post-office box number
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "poboxnumber",
    "value": "22087",
    "box": {
        "page": 1,
        "left": 223.0,
        "top": 125.0,
        "width": 16.0,
        "height": 6.0
    }
}

Valid Feedback

Form Example
4-6 digits 123456
<Keyword> <4-6 digits> Postfach 123456, PF 123456, Brieffach 123456

The keyword can be one of the following: Postfach, PF, Brieffach

reference

Describes a payment reference.

Format

Name Type Description
entity string Must be reference
value string The payment reference with ”, ” as delimiter between reference parts
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "reference",
    "value": "K19218331",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

Valid Feedback

Form Example
A string with length >= 5 This a reference

A string with less than 5 non-space-letters will be rejected.

street

Describes a street in the format <Street name>:<House number> with ”:” as a delimiter between components. All abbreviations (e.g. “str.”) are replaced with the German word “Straße”.

Format

Name Type Description
entity string Must be street
value string Street in the defined format
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "street",
    "value": "Emmy-Noether-Straße:2a",
    "box": {
        "page": 1,
        "left": 162.0,
        "top": 125.0,
        "width": 55.0,
        "height": 6.0
    }
}

Valid Feedback

Form Example
<Streetname>:<Housenumber> ABC Str:1a
<Streetname> <Housenumber> ABC Straße 1a
<Streetname> (without house number) ABC Straße

taxnumber

Describes a German tax number in the format <3-5 digits>/<3 digits>/<4 digits>/<1 digit> with “/” as delimiter between components.

Format

Name Type Description
entity string Must be taxnumber
value string Tax number in the defined format
box bounding box Bounding box of the occurrence including the page number

Example

{
    "entity": "taxnumber",
    "value": "143/163/4028/9",
    "box": {
        "page": 1,
        "left": 501.0,
        "top": 812.0,
        "width": 58.0,
        "height": 6.0
    }
}

Valid Feedback

Form Example
A string containing 11-13 digits 143/163/4028/9

All kinds of delimiters, that are common for tax numbers, are allowed (e.g. ‘/’, ‘-‘). A string without delimiters is also allowed.

text

Describes a plain text entity.

Format

Name Type Description
entity string Must be text
value string Plain text
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "text",
    "value": "Aktenzeichen: K19218331",
    "box": {
        "page": 1,
        "left": 535.0,
        "top": 395.0,
        "width": 25.0,
        "height": 10.0
    }
}

url

Describes the host part of an URI as defined in RFC 3986. http:// is implicitly assumed as URI scheme.

Format

Name Type Description
entity string Must be url
value string The host part of a URI
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "url",
    "value": "www.m-net.de",
    "box": {
        "page": 1,
        "left": 444.0,
        "top": 553.0,
        "width": 50.0,
        "height": 8.0
    }
}

Valid Feedback

Form Example
A valid url string www.gini.net

vat

Describes a German VAT number.

Format

Name Type Description
entity string Must be vat
value string German VAT number in the normalized form (without spaces between the digits and letters)
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "vat",
    "value": "DE188796931",
    "box": {
        "page": 1,
        "left": 453.0,
        "top": 812.0,
        "width": 43.0,
        "height": 6.0
    }
}

Valid Feedback

Form Example
VAT string in valid form DE188796931

Currently only VAT for ‘DE’ ‘GB’ ‘FR’ ‘AT’ allowed.

zipcode

Describes a ZIP code.

Format

Name Type Description
entity string Must be zipCode
value string The ZIP code
box Bounding Box Bounding box of the occurrence including the page number

Example

{
    "entity": "zipCode",
    "value": "18337",
    "box": {
        "page": 1,
        "left": 62.0,
        "top": 25.0,
        "width": 55.0,
        "height": 6.0
    }
}

Valid Feedback

Form Example
4-5 digits 80809