services / company / cloud / 2.0 / requests

Request

URL of the service

https://real-time.data-quality-service.com/companies/v2/

The Company validation service provides the following request

POST /companies/v2?lang=language&searchMethod=...

The /companies/v2/ request returns all available data on the company you entered, or a list of companies. A maximum of 50 hits can be returned.

Most parameters are optional. If you omit them, they either use their default value or are ignored. The default search method is company.

Parameter

Name Description Default

searchMethod

The search method. You can choose from three alternatives
company – Error-tolerant search based on the name and address of the company. This search method returns a maximum of 50 hits. You can control the number and quality of the returned results using the minScore and limit parameters. company is the default value.
tr – Search based on the commercial register number. This search method returns a maximum of 50 hits. You can control the number and quality of the returned results using the minScore and limit parameters.
vat – The method returns always status 200. The VAT ID is just checked for correctness, but not if it is assigned to a company. If the VAT ID is correct, the response attribute "code" is set to VALID_VAT_ID, otherwise to "INVALID_VAT_ID"

company

minScore

Specify the score threshold for matching. This threshold allows you to control the number of displayed hits with a low matching degree. A score of 100 means that only full matches will be displayed. Possible values: 1 to 100.

85

includeDeleted

Specify whether liquidated companies should also be included in the search and be returned. Active companies that were found will always be returned.
true = liquidated companies will be included in the search and will be returned.
false = liquidated companies will not be included in the search.

false

limit

Specify the maximum number of hits returned in the results list. Possible values: 1 to 50.

50

offset

Can be used together with the limit parameter to have the pages of the results list numbered.

0

lang

Language in which warnings and messages will be displayed.
de = German
en = English
fr = French

en

Input

Depending on the search method selected, the relevant input arguments will differ.

searchMethod: company

Name Description Type

company

The company name.

mandatory

zip

The ZIP (postcode)

optional

city

The name of the city.

optional

street

The street and house number.

optional

searchMethod: tr

Name Description Type

trCourt

The name of the court where the company is registered.

mandatory

trType

The type of the entry in the commercial register (HRB, HRA …​).

mandatory

trNo

The number in the commercial register.

mandatory

searchMethod: vat

Name Description Type

vatId

Specify the VAT ID.

mandatory

Sample Request

Example of the company search method: In the BODY, input arguments are passed in JSON format: (Parameter content type: application/json;charset=UTF-8)

POST /companies/v2?lang=de
{
    "company": "Uniserv GmbH",
    "city": "Pforzheim",
    "zip": 75179,
    "street": "Rastatterstr 13"
}

Example of the vat search method: In the BODY, input arguments are passed in JSON format: (Parameter content type: application/json;charset=UTF-8)

POST /companies/v2?lang=de&searchMethod=vat
{
    "vatId": "DE12345678"
}

Response

Successful Request for method=VAT

Result of VAT ID is given in attribute code.

{
   "status": 200,
   "code": "VALID_VAT_ID"
}

Successful Request

If the request results in at least one hit, the following information is returned:

{
   "status": "...",
   "companies": [
     {
        "id": "...",
        "company": "...",
        .....
     }
    ]
}

For each hit, the companies list includes the following information:

Name Description

id

The ID of the company.

company

The company name.

zip

The ZIP (postcode).

city

The name of the city.

street

The street and house number.

trCourt

The name of the court where the company is registered.

trType

The type of the entry in the commercial register (HRB, HRA …​).

trNo

The number in the commercial register.

trStatus

The status of the entry in the commercial register ('active' or 'inactive').

searchMethod

The search method used: company, tr, or vat.

searchScore

The score of the hit, i.e. the quality rating of the match. The value 100 means that the input word and the hit found by matching are fully identical. The hits are returned in descending order of the score.

The X-Total-Count response header displays the number of returned results.

Sample response for successful request

If the request results in at least one hit, its status is always 200.

{
   "status": 200,
   "companies": [
     {
       "id": 4711,
       "company": "Uniserv GmbH",
       "zip": 75179,
       "city": "Pforzheim",
       "street": "Rastatter Str. 13",
       "trCourt": "Mannheim",
       "trType": "HRB",
       "trNo": 501535,
       "trStatus": "active",
       "searchMethod": "company",
       "searchScore": 100
     }
  ]
}

Request failed

If an error occurs, the following response is displayed:

{
   "timestamp": "...",
   "status": "...",        // error code
   "error": "...",         // type of error
   "message": "..."        // error message
}
Status Description

400

Invalid request. Invalid input parameters or request body. Also given for if value is empty or out of range. For method VAT this is returned in case of an invalid country specified.

401

Missing or invalid authorization.

403

The service is not enabled for this account or the maximum number of requests has been reached.

500

Unknown server error.

Sample response for a request where an error occurred.

{
    "timestamp":"2023-02-24T08:03:51.787Z",
    "status":400,
    "error":"Bad Request",
    "message":"Invalid request: general syntax wrong",
    "path":"/"
}