API documentation CertificateParser

Information on the integration of the ZeugnisParser for the automatic analysis of job references.

Release Date: 05/21

Introduction

The verlingo ZeugnisParser API is designed according to the principles of REST set up. Several end points are available:

All access is via HTTPS.

Important: We do not accept unsecured HTTP requests for security reasons. Only HTTPS requests are accepted.

Authentication

Each user of our API receives individual access data. If you are interested in integrating our service, please send us a short email to info@verlingo.de

API Key

You simply specify these credentials as the API key via the HTTP Authorization Header.

HTTP-VERB: ("Authorization", IHR_API-Schlüssel)

HTTP Status Codes

Below is a list of the most important HTTP status codes that the verlingo API outputs and how you can interpret them. In general, 200 codes represent a successful request, 400 codes represent an error in the request data (for example, a mandatory parameter is missing), and 500 codes represent an error on our servers.

Code Meaning
200 OK A successful request
400 Bad Request This is usually due to a syntax error in the request body.
401 Unauthorized Incorrect or missing authentication
404 Not Found The resource could not be found
406 Not Acceptable The format of the request is not supported
417 Expectation Failed The transmitted file could not be analyzed
500, 502, 503 Server Error Server error. Repeat the request after a short time and report to us if the error occurs permanently

Example analysis

A sample analysis is available under the test endpoint below:

GET https://zeugnisanalyse.verlingo.de/v1/beispielanalyse

The test endpoint can be addressed directly without an authorization header and without a special request body and returns a sample response without actually going through the analysis process.


Certificate Analysis

POST https://zeugnisanalyse.verlingo.de/v1/analyse
Please note: As format we use JSON, this must be specified by means of the header content type (application/json).

Request

http-Header:

{ 
  "Content-Type": "application/json"
  "Accept": "application/json"
  "Authorization": IHR_API key
}

http-Body:

{
    "DoAnalysis": {
      "Zeugnis": ["Base64(datei1)", "Base64(datei2)", …],
      "Format": "PDF" | "JPG" | "JPEG" | "PNG"
      "Dokument": "true" | "false"
    }
}

Certificate:

The size of the files per request may not exceed 10 MB must not be exceeded. In addition, the files must be stored in a Base64 encoded string and be UTF-8 encoded.

Important: You can send us several certificates per request in one file or in several files for analysis. The individual pages of a certificate must be coherent and in the correct order.

Format:

We accept the formats PDF, JPG, JPEG, PNG

Document:

Determines whether the images and the analyzed document structure (page, text position, sentences, etc.) of the documents should be returned (default: false).

POST Response

You will always receive a response from our API in JSON format and HTTP status code 200 on a successful response.

Basic structure of the answer

{
    "Zeugnisanalysen": [{
        "Result": "SUCCESS  or WARNING  or ERROR",
        "Message": "message",
        "Gesamtnote": 2.2,
        "GesamtnoteLeistungbeurteilung": 1.9,
        "GesamtnoteVerhalten": 1.7,
        "GesamtnoteSchlussformulierung": 1.5,
        "GesamtnoteProOberkategorie": [{
            "Bezeichnung": "designation",
            "Info": "info",
            "Gesamtnote": 2
        }, {
            "Bezeichnung": "designation",
            "Info": "info",
            "Gesamtnote": 1.8
        }, …
        ],
        "Vorname": "Max",
        "Nachname": "Mustermann",
        "Inhaber": "Max Mustermann",
        "Geburtsdatum": "yyyy-MM-dd",
        "Alter": 29,
        "Firma": "Firma AG",
        "Berufsbezeichnung": "job title",
        "Beschaeftigungsbeginn": "yyyy-MM-dd",
        "Beschaeftigungsende": "yyyy-MM-dd",
        "BeschaeftigungsdauerInMonaten": 34,
        "Zeugnisart": "certificate type",
        "Seitenanzahl": 1,
        "Zeichenanzahl": 2522,
        "Wortanzahl": 241,
        "Zeugnislaenge": "Zu kurz  oder Gut  oder Zu lang",
        "Creationdate": "yyyy-MM-dd",
        "Taetigkeiten": [
            "Taetigkeiten1",
            "Taetigkeiten2",
            …
        ],
        "Auffaelligkeiten": [{
            "Beschreibung": "beschreibung",
            "Details": ["details1", "details2", …],
            "Hinweis": "hinweis",
            "Schweregrad": "leicht or mittel or schwer"
        }, …
        ],
        "UnterdurchschnittlicheSaetze": [{
            "Satz": "Mr. Mustermann has a solid technical knowledge, which he used successfully to accomplish his tasks.",
            "Kategorie": "Expertise",
            "Note": "3",
            "Seite": 1,
            "Paragraph": 17,
            "IndexInParagraph": 0
        }, …
        ],
        "FehlendeKategorien": [{
            "Bezeichnung": "Ability to work & resilience",
            "Kuerzel": "BELAS"
        }, …
        ],
        "Zeugnisaufteilung": [{
            "Zeugniselement": "name",
            "Anteil": 0.15
        }, …
        ],
        "StandortImDokument": [
            2,
            3,
            …
        ]
    }, …
    ],
    "GesamtnoteAggregiert": 2.1,
    "GesamtnoteLeistungbeurteilungAggregiert": 2.3,
    "GesamtnoteVerhaltenAggregiert": 2.1,
    "GesamtnoteSchlussformulierungAggregiert": 1.8,
    }

If you have set the property "Document" to "true", the response will be completed as follows:

{
"Zeugnisanalysen": [
  {
    …,
    "Dokument": {
        "Pages": [
            {
                "PageNr": 1,
                "Images": [
                {
                    "Image": "Base64Image",
                    "Format": "jpg"
                },
                ...
                ],
                "Paragraphs": [
                {
                    "Page": 1,
                    "Index": 0,
                    "Content": "content",
                    "X": 1011,
                    "Y": 570,
                    "Xendpoint": 1476,
                    "Yendpoint": 662,
                    "W": 465,
                    "H": 92,
                    "Sentences": [
                        {
                            "Page": 1,
                            "ParagraphIndex": 0,
                            "Index": 0,
                            "Content": "content",
                            "Rating": 0,
                            "Category": "category",
                            "IsConfident": true or false
                        },
                        ...
                    ]
                },
                ...
                ]
            },
          ...
        ]
      },
      …
  }, …
],
…
}
Info: This describes the complete structure of the JSON response.

Query of the credits

Under the following endpoint the current credits can be retrieved:

GET https://zeugnisanalyse.verlingo.de/v1/credits

The endpoint must be addressed with the authentication described above, but without a request body, and returns in response:

{
    "CurrentCredits": 1500 
}
Icon For Arrow-up