Welcome to BizMachine API!

Extend your CRM with corporate data from over a hundred data sources. Leverage carefully collected, validated and updated BizMachine data. We are building the richest database of companies from the Czech Republic, Slovakia and Germany.

• Current information about companies in CRM
• Real-time market segmentation
• Flexible connection to internal systems

This API is a REST-compliant JSON API. Both request and response bodies should be formatted as valid JSON document.

If API supports multiple datasets, a dataset parameter as part of the URL has to be provided.

Format of the parameter is in ISO 3166-1 alpha-2 in lower case.

Examples:

• cz - Czech dataset
• sk - Slovak dataset
• de - German dataset

Generating API Key

In order to generate an API key, please follow instructions below:

1. Scroll down to list of endpoints and look for "ApiKeys"
2. Select the POST endpoint /v1/ApiKeys/otp/request
3. Click on Try it out on right-hand side and fill in your email "email":"yourEmail@address.com"
4. Click on Execute below
5. You receive One Time Password (OTP) in to the email address you have entered
6. Copy the password
7. Select second POST endpoint /v1/ApiKeys/otp
8. Click on Try it out on right-hand side
9. Paste your OTP from the email into the body "token": "your password",
10. If needed, change date in ExpiresAt as required (date must be in the future)
11. Select Execute
12. Generated ApiKey for you can be found in the response body
13. Copy the ApiKey and paste it into the Value box under the "Authorize" button (can be found on top of the list on the right-hand side)
14. Click on Authorize

To generate an API key, the client has to have an existing, active account.

Using API Key

To authenticate your calls with using API Key add following header with a valid API Key value.

• Headers
  • X-Api-Key: {YOUR_API_KEY}

Make sure you treat API key as any other secret (i.e. passwords).

Example:

curl --location --request GET 'https://api.beta.bizmachine.com/api/v3/companies/basic-infos' \
    --header "X-Api-Key: 4984052df611ff96e5c76d8feb185cd09bec444f811be6e41863cca14a61dbdc"

The API allows you to retrieve localized information for some of the text values. You can specify your language preference by using the standard Accept-Language header:

• Headers
  • Accept-Language: {LANGUAGE_ID}

Currently available languages are:

• EN (English)
• CS (Czech)
• SK (Slovak)

EN (English) is the default language used if the header is not provided.

If applicable (e.g., call initiated by CRM user), the identity of a user is tracked for reporting purposes.

Such API calls have to include the following header:

• Headers
  • X-User: {USER_EMAIL_OR_ID}

To ensure a good service level for all our clients, we are applying rate limits on number of requests per minute and per day. These limits are set and tracked per API key.

The information about the current and remaining API calls per time period are included in each response.

Due to the data refresh, there may be periods of time (typically during the late night) when the service is temporarily unavailable. In such situations, the response will include:

• Status code 503 (service unavailable)
• Header X-Retry-After with an indication of time the service is expected to be restored

Response from every dataset also contains a section called 'meta' that describes the dataset itself. Here is a description of fields that can be found in this section:

Item	Path	Item description	Example	Always populated?
Data source code	meta/ dataSources/ code	Code that identifies a specific data source	cz-ruian	No
Created at date	meta/ createdAt	The oldest date when the item was registered in the dataset instance	2021-03-22T14:16:05.724Z	No
Hash	data/ hash	A control hash ensuring the data integrity	378dbad7b9f4145cad5be6dacea466e58ea86a823e40f03d13d93c8c29106f4b	No

Deprecated v1 endpoints end its support on the 31st of May 2024. All users using these endpoints (listed below) needs to migrate to new alternatives.

This guide describes which endpoints are affected, what are the replacements for deprecated endpoints and how they differ.

List of deprecated v1 endpoints

• GET v1/company/{nationalIn}
• GET v1/embed/company/{nationalIn}
• GET v1/company/customdata
• GET v1/search/company/{query}
• GET v1/vehicles

If you are using one of the above mentioned endpoints, please follow the migration guide or contact support at support@bizmachine.com.

Endpoints alternatives

Deprecated	New alternative
GET v1/company/{nationalIn}	GET {dataset}/v4/companies/{nationalIn}/aggregated-data
GET v1/embed/company/{nationalIn}	POST {dataset}/v4/companies/{nationalIn}/iframe
GET v1/company/customdata	GET {dataset}/v3/custom-data
GET v1/search/company/{query}	GET {dataset}/v4/companies/suggest
GET v1/vehicles	GET {dataset}/v4/vehicles

Note, that all new endpoints have {dataset} option. You can specify a country, you are interested in. Valid values are: cz, sk, hu. If {dataset} is not provided, it defaults to cz.

New endpoints also no longer provides detailed API usage in Meta part of the payload. Meta is now used to provide metadata information about current payload related to the called endpoint.

Migrating v1/company/{nationalIn}

A new alternative to v1/company is aggregated-data endpoint. The Aggregated Data endpoint is your go-to solution for accessing essential company-related data in a streamlined and easy-to-implement manner. This endpoint serves as a centralized hub for extracting essential company-related data, encompassing the "Basic-Infos" dataset along with selected values from diverse datasets such as Contacts, Metrics, Risks, Indicators, NACE codes, Eshops, and Locations.

The deprecated v1/company endpoint had different outputs based on template provided. Below are migration guides (XLSX files) for specific templates, containing differences between the endpoints mapping, notes, data availability, and what values should be used instead:

• Automotive Template
• Basic Template
• Premium Template

Example:

Call GET https://api.bizmachine.com/v1/company/05450641 will be migrated as GET https://api.bizmachine.com/cz/v4/companies/05450641/aggregated-data

Migrating v1/embed/company/{nationalIn}

A new alternative for this deprecated endpoint is POST {dataset}/v4/companies/{nationalIn}/iframe.

The endpoint will provide a direct shareable link with IFrame options.

Endpoint changed HTTP method from GET to POST.

Migrating v1/company/customdata

To get Custom Data, use endpoint GET {dataset}/v3/custom-data. This endpoint changes both input parameters and returned payload as well.

To specify a company, you no longer provide it as RegistrationNumbers but as NationalIn. Filtering options were extended, so please pay attention to those changes.

Migrating v1/search/company/{query}

New alternative changed naming and form of the endpoint. It's not called Search anymore, but Suggest.

Instead of searching using route v1/search/company/Bizmachine, it's now using query parameter to pass down query GET {dataset}/v4/companies/suggest?query=Bizmachine. The biggest change for this endpoint is its payload. We no longer provide locations (Premises) and entire payload is targeted to company information.

Migrating v1/vehicles

Alternative to v1/vehicles is {dataset}/v4/vehicles. There are small changes and differences between the endpoints. Most notably it's not using NationalIn (ičo), but rather Company Unique Id, which consists of dataset and NationalIn value.

NationalIn: 05450641 -> UniqueId: cz-company-05450641

Example: Call GET https://api.bizmachine.com/v1/vehicles?Company.Bid=05450641 will be migrated as GET https://api.bizmachine.com/cz/v4/vehicles?Company.UniqueId=cz-company-05450641

Troubleshooting

I'm getting 400 error

Error 400 means bad input to API. Double check the documentation and your input parameters, if they have correct name and format. Most of the endpoints changed format, path, and naming.

I'm getting 403 error

If you are getting 403 HTTP Code response from new endpoints, please contact support at support@bizmachine.com.

This workflow will show you how to add companies to a tag and then use this tag as a parameter for one of our data endpoints.

Filtering BizMachine API with a tag is a common use case allowing you to get data only for the companies you specify. Tag is a list of companies to which you can add or take away companies as needed.

The tags can be managed in Prospector as well. You will find them there under the name "Company Lists."

Please note that you can create a new tag solely in Prospector; this feature is not available through BizMachine API yet.

In the short workflow below, we will show how you can add companies to a tag and then filter one of our data endpoints by the tag.

Step 1: Add company to a tag

To add a company to the tag, you will need to know the following:

• Dataset (cz, sk...)
• National In (ICO...) of the company you want to add
• Tag UID

CURL example:

curl --location --request POST 'https://api.bizmachine.com/prospector/cz/v2/companies/05450641/tags/a518e43c-0298-4cbc-92da-529b29ce3b42' \
--header "X-Api-Key: your-api-key"

If you created a new tag in Prospector and are trying to figure out the Tag UID, do the following:

• Open the tag you created in Prospector
• Look at the URL it should be in this format:
• https://prospector.bizmachine.com/cz/my-portfolio?tags=a518e43c-0298-4cbc-92da-529b29ce3b42
• Copy the code after "tags=" that is your Tag UID.

Step 2: Using tag as a parameter on company dataset

You can use the tag as a parameter to get data only for selected companies. For this, you will need to know following:

• Dataset (cz, sk...)
• Tag UID

CURL example:

curl --location --request GET 'https://api.bizmachine.com/cz/v3/companies/basic-infos?Tag.Uid=a518e43c-0298-4cbc-92da-529b29ce3b42' \
--header "X-Api-Key: your-api-key"

Constructing PATCH JSON

Our PATCH {dataset}/v2/tags/{uid}/companies endpoint requires specific json structure to be send in the body. This section contains some examples on how to correctly construct it.

Allowed operations: add, remove
Allowed path: /companyTags

Adding new companies to tag

[
    {
        "path": "/companyTags",
        "op": "add",
        "value": {"Bid": "05450641"}
    },
    {
        "path": "/companyTags",
        "op": "add",
        "value": {"Bid": "09540385"}
    }
]

Removing companies from tag

[
    {
        "path": "/companyTags",
        "op": "remove",
        "value": {"Bid": "05450641"}
    }
]

Common issues

I created a new tag, and add companies however the company dataset is not returning any data

Please remember that a new tag might not be available on the API for 15 minutes after its creation.

If the dataset is empty even after 15 minutes from creating the tag, don't hesitate to get in touch with support@bizmachine.com

API is returning 401 unauthorized

Your API key is not authorized to get data from the specific dataset.

Please make sure that:

• You specified header X-Api-Key with the correct API key as its value
• Your API key is not expired. In that case, please generate a new API key
• You generated the API key with a service account which have all the necessary rights for this dataset

If the problem persists, please get in touch with support@bizmachine.com