Bisnode Business Contacts API User Guide

Introduction

Generated from bbc.raml

The Bisnode Business Contacts (BBC) API delivers European data on companies, worksites and employments. We continuously update the data as changes are made.

For technical issues and feedback regarding the API, please contact Bisnode at kundservice.marknad.se@bisnode.com.

API Change log

2018-04-26

You can now get search results in a specific language. See the language parameter for more information.

2018-04-09

Added address source information when fetching entities.

2018-03-28

Subsidiaries added to the company group block where available. Contact your sales representative for more information.

2017-04-11

Added rate limiting to all API requests. It's currently set to 50 requests per second.

2017-02-02

Added selection. See the selection section below.

Entities and endpoints

The BBC API provides three types of resource entities: companies, worksites, and employments.

Examples and 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.

The resource types companies, worksites and employments are described below.

Companies

General data at company level. This provides a good overview of a company with data such as VAT number, official address, basic financials, etc.

Worksites

Worksites represents places of work related to a company and a company may contain several worksites. Worksite related data contains information such as postal address, visit address and contact details. Links are provided to the parent company as well as any connected employments.

Employments

Employments represents the "contacts" part of the API. Note that employments refer to contacts and decision makers of a company. It is not a list of all employees of the company. The employment endpoint provides data such as names, positions and contact details. All employments link back to both its connected parent company and its worksite. An employment entity is not necessarily equal to a person as a person might have more than one employment (such as roles in different company boards).

Search and download

The following endpoints are available for searching and downloading resources.

  • /companies - Search companies using the available request parameters
  • /companies/{companyId} - Download a company resource
  • /worksites - Search worksites using the available request parameters
  • /worksites/{worksiteId} - Download a worksite resource
  • /employments - Search employments using the available request parameters
  • /employments/{employmentId} - Download an employment resource

Keep your data up to date

For each entity there is a changes endpoint that lets you ask for all changes on that entity since a given date. Its a batching API where you supply one or more queries and get a response for each. See the example at the bottom for details.

  • /companies/changes returns for each request a list of changed fields and added and removed worksites.
  • /worksites/changes returns for each request a list of changed fields and added and removed employments.
  • /employments/changes returns for each request a list of changed fields

Currently we limit the query size to 1000.

Selection (Filtering)

With selection you can get a list of only does enties that matchs you criteras. It looks a bit like search but you start out with the full dataset and cut way everything that does not match you criteras.

An example could be that you want all companies in Stocholm sweden that has more than 100 employes

Working with VAT numbers and Nordic organization numbers

The BBC 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/Nordic organization numbers the API provides the possibility of searching by organization 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 BBC 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.

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 BBC 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 your CLIENTID and SECRET.

Example in cURL

curl -H "Content-Type: application/x-www-form-urlencoded"\
     -X POST -d 'grant_type=client_credentials&scope=bbc'\
     --user $CLIENTID:$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 "Bisnode"

curl -H "Authorization: Bearer eyJhb...seAtPCCQ"\
     https://bbc.bisnode.com/v2/worksites?generalName=Bisnode

Reusing the access token

After you have fetched an access token you should save it and use it for subsequent calls to the BBC 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 BBC 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

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 BBC 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.

API Versioning

What constitutes an API version

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. Client developers should thus prepare their client app's for the possibility of added fields (in which case the schemas will also be updated to reflect this).

Providing API version

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

Resources

Companies

Search, download and query changes for companies

get

Search/filter by provided parameters

Company resource entity. A company may contain one or more worksites.

get

Get a company resource

head

See description of GET request for this endpoint

Retrieve changes since specified date

post

Get information about changes since given time and date for the specified companies. A date and time is specified for each company ID in the request body. Information about updates that have occurred after this date and time are returned in the response.

This endpoint should be used in conjunction with GET /companies/{companyId} to download the changed entities. When you download a company resource through /companies/{companyId} the $lastModified field contains the date and time when that resource was last updated. Use that value in the since field when querying for changes.

Worksites

Search, download and query changes for worksites

get

Search/filter by provided parameters

Worksite resource entity. A worksite is a physical unit within a company.

get

Get a worksite resource

head

See description of GET request for this endpoint

Get changes since specified date.

post

Get information about changes since given time and date for the specified companies. A date and time is specified for each worksite ID in the request body. Information about updates that have occurred after this date and time are returned in the response. This endpoint should be used in conjunction with GET /worksites/{worksiteId} to download the changed entities. When you download a company resource through /worksites/{worksiteId} the $lastModified field contains the date and time when that resource was last updated. Use that value in the since field when querying for changes.

Employments

Search, download and query changes for employments

get

Search/filter by provided parameters

Employment resource entity

get

Get a employment resource

head

See description of GET request for this endpoint

Get changes since specified date.

post

Get information about changes since given time and date for the specified employments. A date and time is specified for each employment ID in the request body. Information about updates that have occurred after this date and time are returned in the response. This endpoint should be used in conjunction with GET /employments/{employmentId} to download the changed entities. When you download an employment resource through /employments/{employmentId} the $lastModified field contains the date and time when that resource was last updated. Use that value in the since field when querying for changes.

Countries

List all countries covered by this API

get

List all countries covered by this API

head

See description of GET request for this endpoint

Company selection

Returns count of hits within selection

get

Extract company selection

Returns all the company IDs within selection.

get

Worksite match

Initiate matching.

post

Fetch matching.

get

Worksite selection

Returns count of hits within selection

get

Extract worksites selection

Returns all the worksite IDs within selection.

get

Employments selection

Returns count of hits within selection

get

Refer to /codetypes/XX for complete list of available codes for each codetype where XX is the codetype.

Extract employments selection

Returns all the employment ID within selection

get

Refer to /codetypes/XX for complete list of available codes for each codetype where XX is the codetype.

Codetypes

Returns different the different kind of codes that are used within BBC API

get