API documentation contract check

Information on the integration of the contract check for the automatic analysis of employment contracts.

Release Date: 03/22

Introduction

The verlingo contract check API is designed according to the principles of REST built. Several endpoints 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 following test endpoint

GET https://legal.verlingo.de/arbeitsvertrag/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.


Contract check

POST https://legal.verlingo.de/arbeitsvertrag/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:

{
    "Documents": [
      {
        "format": "pdf" | "jpg" | "jpeg" | "png",
        "doc": "Base64"
      },
      ...
    ]
}

Document:

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: If you send multiple files, we will assume that it is a single employment contract.

Format:

We accept the formats PDF, JPG, JPEG, PNG

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

{
    "Result": {
        "ContractualPartner": {
            "Employer": {
                "CompanyName": {
                    "Value": "Muster-GmbH",
                    "DocId": 1,
                    "Pageno": 1,
                    "CropNo": 3
                }
            },
            "Employee": {
                "FirstName": {
                    "Value": "Max",
                    "DocId": 1,
                    "Pageno": 1,
                    "CropNo": 3
                },
                "LastName": {
                    "Value": "Muster",
                    "DocId": 1,
                    "Pageno": 1,
                    "CropNo": 3
                }
            },
            "PlaceOfJurisdiction": null
        },
        "Employment": {
            "Occupation": {
                "Value": "technischer Angestellter",
                "DocId": 1,
                "Pageno": 1,
                "CropNo": 7
            },
            "Activities": null,
            "Workplace": {
                "Value": "Musterstadt",
                "DocId": 1,
                "Pageno": 1,
                "CropNo": 8
            },
            "Begin": {
                "Value": "01.03.2019",
                "DocId": 1,
                "Pageno": 1,
                "CropNo": 9
            },
            "End": null,
            "TypeOfEmployment": "Unlimited" | "Temporary" | null
        },
        "WorkingHours": {
            "WeeklyHours": {
                "Value": "40",
                "DocId": 1,
                "Pageno": 1,
                "CropNo": 14
            },
            "OvertimeIncluded": {
                "Value": "8",
                "DocId": 1,
                "Pageno": 1,
                "CropNo": 14
            },
            "OvertimeRegulation": {
                "References": [
                    {
                        "DocId": 1,
                        "Pageno": 1,
                        "CropNo": 14
                    }
                ]
            },
            "Workweek": null
        },
        "Compensation": {
            "AnnualSalary": null,
            "MonthlySalary": {
                "Value": "6500",
                "DocId": 1,
                "Pageno": 2,
                "CropNo": 4
            },
            "HourlySalary": null,
            "SpecialPayments": {
                "References": [
                    {
                        "DocId": 1,
                        "Pageno": 2,
                        "CropNo": 6
                    }
                ]
            },
            "VoluntarinessAndRevocation": null
        },
        "Vacation": {
            "VacationDays": {
                "Value": "zwei",
                "DocId": 1,
                "Pageno": 2,
                "CropNo": 12
            },
            "VacationDaysLegally": null
        },
        "NoticePeriods": {
            "ProbationaryPeriod": {
                "Value": "sechs Monate",
                "DocId": 1,
                "Pageno": 1,
                "CropNo": 12
            },
            "DeadlineProbationaryPeriod": {
                "Value": "vier Wochen",
                "DocId": 1,
                "Pageno": 1,
                "CropNo": 12
            },
            "CancellationPeriod": {
                "Value": "einem Monat zum Ende des Kalendervierteljahres",
                "DocId": 1,
                "Pageno": 2,
                "CropNo": 10
            },
            "CutoffPeriod": {
                "References": [
                    {
                        "DocId": 1,
                        "Pageno": 3,
                        "CropNo": 7
                    },
                    {
                        "DocId": 1,
                        "Pageno": 3,
                        "CropNo": 8
                    },
                    {
                        "DocId": 1,
                        "Pageno": 3,
                        "CropNo": 9
                    }
                ]
            },
            "CutoffPeriodValue": {
                "Value": "drei Monaten",
                "DocId": 1,
                "Pageno": 3,
                "CropNo": 8
            }
        },
        "CollectiveAgreement": null,
        "AdditionalAgreements": {
            "NonCompetitionClause": null
        },
        "Document": {
            "Pages": [
                {
                    "Pageno": 1,
                    "Paragraphs": [
                        {
                            "CropNo": 3,
                            "x": 561.5490307867731,
                            "xEndpoint": 1916.622006841505,
                            "y": 473.6719064893188,
                            "yEndpoint": 678.6940749697702,
                            "width": 1355.072976054732,
                            "height": 205.02216848045143,
                            "scaleY": 0.7072405929304447,
                            "scaleX": 0.7069729947601774,
                            "CropContent": "Null",
                            "Text": "der Muster-GmbH, vertreten durch ihren Geschäftsführer Max Muster, Musterstraße 1, 11111 Musterstadt - im folgenden: „Arbeitgeber“ -",
                            "TextConfidence": 93,
                            "words": [
                                {
                                    "x": 19.802736602052452,
                                    "y": 24.03708182184603,
                                    "w": 59.40820980615735,
                                    "h": 31.106811769447802,
                                    "text": "der",
                                    "confidence": 93
                                },
                                ...
                            ],
                            "textlines": [
                                {
                                    "text": "der Muster-GmbH, vertreten durch ihren Geschäftsführer Max Muster,\n",
                                    "confidence": 93,
                                    "fontsize": 15,
                                    "x": 5.657924743443557,
                                    "y": 9.897621926642483,
                                    "w": 1345.1716077537058,
                                    "h": 66.45546150745668
                                },
                                ...
                            ],
                            "NamedEntities": [
                                {
                                    "label": "Firmenname",
                                    "value": "Muster-GmbH",
                                    "start": 4,
                                    "end": 15
                                },
                                ...
                            ],
                            "Labels": [
                                {
                                    "label": "paragraphType",
                                    "value": "Vertragspartner",
                                    "probability": 0.99
                                },
                                ...
                            ],
                            "DocId": 1,
                            "Pageno": 1
                        },
                        ...
                    ],
                    "ImageWidth": 2481,
                    "ImageHeight": 3508,
                    "ImageB64": "Base64",
                    "PageText": "pageText",
                    "CategoryNumeric": 5,
                    "Category": "Sonstiges",
                    "CategoryProbability": 1,
                    "Language": "de",
                    "LanguageProbability": 1,
                    "DocId": 1,
                    "ImageFormat": "jpeg"
                },
                ...
            ]
        },
        "Remarks": [
            {
                "Title": "Mindestlohn eingehalten",
                "Content": "Ihr Arbeitslohn ist höher als der Mindestlohn und ist damit gesetzeskonform.",
                "Level": "hint",
                "Category": "Vergütung",
                "Trigger": [
                    "mindestlohnUeberschritten"
                ],
                "LegalReference": {
                    "lawBook": "MiLoG",
                    "Section": "1",
                    "SubSection": "1"
                }
            },
            ...
        ]
    }
}
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://legal.verlingo.de/arbeitsvertrag/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