Bisnode Business Contacts

 

Overview

Bisnode Business Contacts in 2 minutes

With Bisnode Business Contacts you can:
  • Get access to 40 million business contacts in 21 European countries
  • Identify not only companies, but also related worksites and decision makers
  • Make sure all your company data is always updated and correct
  • Create a single customer view across all your systems and platforms with unique ID:s for each entity
  • Ensure compliance of your company data management to GDPR
 
 

European company data available through a single API

Real time updates of customer data in all your business systems

Bisnode Business Contacts provides you with one integration access to unique European Company data in 21 countries. Integration with our API will ensure updated customer data in all your business systems. That creates an opportunity to improve your sales process and customer experience throughout the customer journey.


Get help to be compliant with GDPR

Get a single customer view with our unique ID

One key concept within Bisnode Business Contacts is the unique entity ID. This is designed to be a unique, persistent ID for entities within Bisnode, which facilitates for you to be able to get a single customer view across all your databases and systems. This is a necessity to be GDPR-compliant.

 

Structure your data and find relations

Identify not only companies, but also related offices and decision makers

There are three different entity types in the Bisnode Business Contacts API: Company, Worksite and Employment. Each entity has its own unique ID. From Company comes the ID for all associated Worksites, and from each Worksite comes the ID for all associated Employments. This means that you can create a structured hiarchy in your company data, and identify relevant relations and decision makers for your business.

 

Key Features

Find new customers and develop your existing

Bisnode provides integrated real-time data for validation, qualification and enrichment derived from company data. Access to this data enables you to optimise each transaction. With Bisnode Business Contacts, you can speed up your sales, improve the selection of target groups, and support decision-makers.

 

Documentation

 

How to use the API

This guide is intended to help you get going with your integration against the Bisnode Business Contacts API. It serves as a complement to the  Endpoint Reference  and aims to bring a high level understanding of the key concepts of the platform.
 
Schemas are provided for all entity types in this documentation. Most data provided in this API is optional, i.e., a particular field specified in the schema may not appear in the response if no such information is available for that particular entity. An API client should keep this in mind and properly handle missing information.
 
For questions and support, please contact Bisnode at api-support@bisnode.com
 
 

Entity types and ID:s in Bisnode Business Contacts API

One key concept within Bisnode Business Contacts is the unique entity ID. This is designed to be a unique, persistent ID for entities within Bisnode.
 
There are three different entity types in the Bisnode Business Contacts API:
 
Company
The legal, cohesive company, which may have several subordinate worksites
 
Worksite
The physical worksite, which may comprise a head office or branch
 
Employment
Decision makers at a particular worksite/office
 
Each entity has its own unique ID. From Company comes the ID for all associated Worksites, and from each Worksite comes the ID for all associated Employments.
 
 

Key Features

Search
This method is recommended when direct contact exists with somebody who is able to confirm an identity – such as, for example, via a CRM, app or the web.
 
Select
Select is used in order to find new customers and to make a selection from a large amount of prospects for a campaign.
 
Match
This method is recommended for companies whose customer data is unsatisfactory, or when one wishes to supplement a request with Bisnode’s unique ID number in order to exclude certain entities from a prospect selection.
 
Download
Through Match, Select och Search you can identify the entities that are of interest for you. Via Download you can then get updated and enriched information about these entities.
 
Subscribe
Keep your data updated and enriched over time by subscribing for changes and new entitites.
 
Read more about each key feature below, and in the section Endpoint reference.
 
 
Search process
 
1. The client sends a search request to the API containing criteria with significant identification value
 
2. The API responds with a result that contains basic data in order to confirm the identity
 
3. A new request is sent, in order to retrieve further information about the selected entity. For output, see the Download section.
 
Select process
 
1. Select the entities you wish to be included in your selection by choosing selection criteria
 
2. In the next step, you get the number of entities within your chosen selection
 
3. If you are happy with the count, you can go further and retrieve the unique IDs within your selection, which will enable you to exclude any existing IDs
 
4. Finally, you can download all the selected entities to obtain complete information. For content of the output, see the Download section.
 
 
Match process
 
1. The integrator submits a query to the matching endpoint containing those entities that are to be matched
 
2. The response contains Matching Type, Status, Customer id and Bisnode Business Contacts ID (worksite and company ID)
 
3. If Multiple hits are chosen you can review the hits and choose the ones that are correct
 
4. Download your matched customers. For content of the output, see the Download section.
 
 
Download process
 
Submit Company, Worksite or Employment ID:s, retrieved from Search, Select or Match. There are three available information packs to download: Company, Worksite and Employment. See Endpoint Reference for content in each pack.
 
From Company comes the ID:s for all associated Worksites, and from each Worksite comes the ID:s for all associated Employments, so you can combine these information packs and create a structure and hierarchy in your company data.
 
Note that there is variation in the coverage of the variables in the information packages and in different countries.
 
Countries that are covered in Bisnode Business Contacts are Austria, Belgium, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Italy, Latvia, Lithuania, the Netherlands, Norway, Poland, Russia, Slovakia, Spain, Sweden, Switzerland and United Kingdom.
 
 
Subscribe process
 
1. The integrator submits a query to the subscribe endpoint containing Bisnode Business Contacts IDs from your previous download, that are of interest to monitor
 
2. If the entity has changed since last modified date, you will get information which fields that have changed, and if there are any deleted or new worksites and/or employments
 
3. Download your updated customers with complete information
 
 

Working with VAT and National Registration Numbers

The Bisnode Business Contacts API uses its own entity IDs to download and request changes for companies, worksites and employments. This means that to download and request changes for an entity you need to know its entity ID.
 
To make it easy to work with VAT or national registration numbers, the API provides the possibility of searching by registration numbers and VAT numbers. When downloading a company resource these can be found in the fields nationalRegistrationNumber and vatNo, respectively. You may also search a company or worksite based on these numbers. The outline below illustrates how to convert organization or VAT numbers to Bisnode Business Contacts IDs.
 
Use the Search endpoint for companies and filter on nationalRegistrationNumber and companyStatus like so:
 
1. Search active companies with the desired VAT/registration number, for example: /companies?companyNumber=5564363421&companyStatus=ST00. The companyNumber parameter is used to specify either the VAT or national registration number. The parameter companyStatus=ST00 means that only active companies will be returned.
 
2. Make sure there is only one hit among the search and extract the ID of that hit. You can now use this ID to download complete company information and use it to query for changes. It is recommended that you save this ID along with the company information to easily query for changed properties.
 
You can do the same for official worksite numbers if this exists in the country, for example for SE you can search on "cfar".

Changes and versioning

API version is provided in the base of the requested URL in the form of "v1", "v2" etc. Only major version numbers are used.

API versions are raised only on breaking (i.e. backwards incompatible) changes in the API. Fields may be added but will never be removed during an API version lifecycle. When developing your application, take care to ensure that your application is able to handle additional fields.

 

Authentication

Authentication using OAuth2

Bisnode's latest APIs use OAuth2 for authentication. For all API requests, you need to supply an access token in order to authenticate yourself. To obtain such an access token you need to submit your CLIENT_ID and CLIENT_SECRET to Bisnode's authentication endpoint at https://login.bisnode.com/as/token.oauth2. The access token is then passed along in the Authorization header to all API requests. Follow the instructions below to learn how to do this.

 

Get and Use the Access Token

Step 1. Get the Access Token

To get an access token you need to make a POST request to https://login.bisnode.com/as/token.oauth2 using the following HTTP header: Content-Type: application/x-www-form-urlencoded and the following request body: grant_type=client_credentials&scope=bci The request must be authenticated using HTTP Basic authentication and your CLIENT_ID and CLIENT_SECRET.

Example in cURL
curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d 'grant_type=client_credentials&scope=bci' \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     https://login.bisnode.com/as/token.oauth2
 
Example response
{
  "access_token": "eyJhb....seAtPCCQ",
  "token_type": "Bearer",
  "expires_in": 7199
}
 
Step 2. Use the Access Token

Supply your access token with all requests to the API using the HTTP Authorization header: Authorization: Bearer <your access token here> You should reuse the access token for multiple calls to the API. See the next section on recommended usage.

 
Example in cURL - search for person
curl -X GET \
     -H "Authorization: Bearer eyJhb...seAtPCCQ" \
     https://api.bisnode.com/consumerintelligence/person/v2/?firstName=Sven&familyName=Svensson&streetAddress=Vasagatan 9&sourceCountry=SE


Reusing the Access Token

After you have fetched an access token you should save it and use it for subsequent calls to the API. There is no limit on the number of calls it can be used for, but it will expire after a certain time.

We recommend that you use the expires_in field to determine when to request a new access token. It specifies the number of seconds the token will be valid for. Because of possible delays in network communication as well as delays between checking the timestamp and transmitting the actual API request, it is a good idea to request a new token a few seconds before it is about to expire. This minimizes the risk of accidentally using an expired token.

The following pseudo code illustrates how to use the authentication endpoint together with the API.

function make_authorized_api_request():
    token = get_cached_access_token()
    if token == null or is_soon_to_be_expired(token):
        token = get_new_access_token()
        save_to_cache(token)
    make_api_call(token)


function get_new_access_token():
    token = get_token_from_auth_endpoint()
    token.expiration_timestamp = now().add_seconds(token.expires_in)
    return token


function is_soon_to_be_expired(token):
    # Add time margin to avoid token expiring during call
    if now().add_seconds(60) >= token.expiration_timestamp:
        return true
    return false

Get Access

API Access

Bisnode provides API access for client developers by means of a CLIENTID and a SECRET. The client developer uses the CLIENTID and SECRET to get an access token from Bisnode's authentication endpoint at https://login.bisnode.com/as/token.oauth2. The access token is then passed along in the Authorization header to all Bisnode Business Contacts API requests.
 
Step 1. Get the access token
 
To get an access token you need to make a POST request to https://login.bisnode.com/as/token.oauth2 using the following HTTP header: Content-Type: application/x-www-form-urlencoded and the following request body: grant_type=client_credentials&scope=bbc. The request must be authenticated using HTTP Basic authentication and a base64-encoded string CLIENTID:SECRET.
 
Example in cURL
 

curl -H "Content-Type: application/x-www-form-urlencoded"\

     -X POST -d 'grant_type=client_credentials&scope=bbc'\

     --user base64_encode($CLIENTID:$SECRET)\

 
Example response

{

  "access_token": "eyJhb....seAtPCCQ",

  "token_type": "Bearer",

  "expires_in": 7199

}

 
Step 2. Use the access token
 
Supply your access token with all requests to the API using the HTTP Authorization header: Authorization: Bearer <your access token here>. You should reuse the access token for multiple calls to the API. See the next section on recommended usage.
 
Example in cURL - search for "Bisnode"
 
curl -H "Authorization: Bearer eyJhb...seAtPCCQ"\
 
 
Reusing the access token
 
After you have fetched an access token you should save it and use it for subsequent calls to the Bisnode Business Contacts API. There is no limit on the number of calls it can be used for, but it will expire after a certain time.
 
We recommend that you disregard the value of the expires_in field and that you simply keep using the same access token until it expires, at which point the API will return an HTTP status of 401 Unauthorized. When that happens you should retrieve a new access token from the authentication endpoint and retry the operation. Care should be taken to not introduce an endless loop of failed API requests and getting new access tokens.
 
The following pseudo code illustrates how to use the authentication endpoint and Bisnode Business Contacts API.
 

function make_authorized_bbc_api_request():

    if not has_cached_access_token():

        retrieve_new_access_token()

 
 
try:
 

 make_bbc_api_call()

    except bbc_error_status_401_unauthorized:

        retrieve_new_access_token()

        make_bbc_api_call()

 
Backwards compatibility for CRM integrators
 
To enable use of several users in the same client, use the special header X-BISNODE-USERNAME. This should only be used for backwards comparability for legacy clients. The X-BISNODE-USERNAME enables us to track individual users' usage.
 
X-BISNODE-USERNAME: user1
 
Hyperlinks
 
HAL
 
Resources may point to other API resources by means of hyperlinks. The format used for exposing these relations is Hypertext Application Language (HAL).. The content type of all Bisnode Business Contacts documents is thus "application/hal+json" and clients should treat them as any JSON data but with the extra benefit of having provided links to related resources.
 
Benefits
 
Links promote the idea of explorability and makes it possible to fetch documents right from the web browser (provided an access token is sent along with the request) for casual browsing of the data before connecting through more advanced client applications.
 
Search navigation
 
Links are also used for easy navigation of search results for the /worksites and /employments endpoints. By default two links are always available in this context; "first" and "last". If the search result spans more than one page (i.e "hitsReturned" is less than the value of "hitsTotal"), "previous" and "next" links will also be available depending on the current position.