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

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:

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

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

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

/companies get

get

Search/filter by provided parameters

Request
Response

Query Parameters

maxSize: (integer - default: 10 - maximum: 10000)
Max number of results to provide in each resultset
Example:
```
20
```
offset: (integer - maximum: 10000)
The current offset in the total result set hit count (totalHits in the search result data)
Example:
```
10
```
fulltext: (string)
Search within all fields at once, for example company name and city (see example below)
Example:
```
Bisnode Stockholm
```
country: (string - pattern: ^[A-Za-z]{2}$)
ISO country code.
Available country codes may be retrieved through the /countries endpoint.
Example:
```
DE
```
companyLegalName: (string)
Search by company legal name
phone: (string)
Search by company phone numbers.
Example:
```
+46 855805900
```
companyType: (string)
Search by type of company
Example:
```
TY50
```
companyStatus: (string)
Search by status of the company
Example:
```
ST00
```
companyNumber: (string)
Search by company national registration number or VAT number
companyAddress: (string)
Search by company postal address
companyCity: (string)
Search by company postal city
companyZipcode: (string)
Search by company postal zipcode
companyCreationDate: (string)
Search by company creation date. Specified as an interval, bounds are inclusive. One of the bounds can be omitted.
Example:
```
[2015-12-12,]
```

HTTP status code 200

A company-search resource

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/company-search.schema.json",
    "companies": [
        {
            "id": "1:100277670",
            "name": "Bisnode AB",
            "country": "SE",
            "postalAddress": {
                "city": "SOLNA"
            },
            "status": {
                "code": "ST00",
                "name": "Active"
            },
            "type": {
                "code": "TY50",
                "name": "Private company"
            },
            "numberOfWorksites": 1,
            "_links": {
                "company": {
                    "href": "https://bbc.bisnode.com/v2/companies/1:100277670"
                }
            }
        },
        {
            "id": "1:100325911",
            "name": "Bisnode Sverige AB",
            "country": "SE",
            "postalAddress": {
                "city": "SOLNA"
            },
            "status": {
                "code": "ST00",
                "name": "Active"
            },
            "type": {
                "code": "TY50",
                "name": "Private company"
            },
            "numberOfWorksites": 14,
            "_links": {
                "company": {
                    "href": "https://bbc.bisnode.com/v2/companies/1:100325911"
                }
            }
        },
        {
            "id": "1:100357443",
            "name": "Bisnode Kredit AB",
            "country": "SE",
            "postalAddress": {
                "city": "SOLNA"
            },
            "status": {
                "code": "ST00",
                "name": "Active"
            },
            "type": {
                "code": "TY50",
                "name": "Private company"
            },
            "numberOfWorksites": 7,
            "_links": {
                "company": {
                    "href": "https://bbc.bisnode.com/v2/companies/1:100357443"
                }
            }
        }
    ],
    "maxSize": 3,
    "offset": 0,
    "hitsReturned": 3,
    "hitsTotal": 5,
    "_links": {
        "next": {
            "href": "https://bbc.bisnode.com/v2/companies?companyLegalName=bisnode&companyStatus=ST00&companyType=TY50&maxSize=3&offset=3"
        },
        "last": {
            "href": "https://bbc.bisnode.com/v2/companies?companyLegalName=bisnode&companyStatus=ST00&companyType=TY50&maxSize=3&offset=3"
        },
        "self": {
            "href": "https://bbc.bisnode.com/v2/companies?companyLegalName=bisnode&maxSize=3&companyStatus=ST00&companyType=TY50"
        },
        "first": {
            "href": "https://bbc.bisnode.com/v2/companies?companyLegalName=bisnode&companyStatus=ST00&companyType=TY50&maxSize=3"
        }
    }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Company search result",
  "type": "object",
  "description": "Company search result schema from the Bisnode Business Contacts API",
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "City"
        }
      },
      "additionalProperties": false
    },
    "company": {
      "type": "object",
      "description": "A company search result entity",
      "properties": {
        "name": {
          "type": "string",
          "description": "The legal name of the company"
        },
        "country": {
          "type": "string",
          "description": "The ISO country code of this company's country"
        },
        "id": {
          "type": "string",
          "description": "ID of company"
        },
        "type": {
          "type": "object",
          "description": "The type of company (code and name)",
          "properties": {
            "code": {
              "type": "string",
              "description": "The type of company represented as a code"
            },
            "name": {
              "type": "string",
              "description": "The name or description of the company type"
            }
          },
          "additionalProperties": false,
          "required": ["code", "name"]
        },
        "status": {
          "type": "object",
          "description": "The status of the company (code and name)",
          "properties": {
            "code": {
              "type": "string",
              "description": "The status of the company represented as a code"
            },
            "name": {
              "type": "string",
              "description": "The name or description of the company status"
            }
          },
          "additionalProperties": false,
          "required": ["code", "name"]
        },
        "numberOfWorksites": {
          "type": "integer",
          "description": "The number of worksites connected to this company"
        },
        "postalAddress": {
          "$ref": "#/definitions/address"
        },
        "_links": {
          "type": "object",
          "properties": {
            "company": {
              "type": "object",
              "description": "URL for downloading this search hit",
              "properties": {
                "href": {
                  "type": "string"
                }
              }
            }
          },
          "required": ["company"],
          "additionalProperties": false
        }
      },
      "required": ["id", "name", "country", "_links"],
      "additionalProperties": false
    }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "companies": {
      "type": "array",
      "description": "A list of company search results",
      "items": {
        "$ref": "#/definitions/company"
      }
    },
    "_links": {
      "type": "object",
      "description": "Links for navigating the search result. Links of type 'first' and 'last' will always be present while 'previous' and 'next' only will be available when applicable.",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL of the current search result"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the previous search result page (if avaialable)"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the next search result page (if avaialable)"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "first": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the first search result page"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "last": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the last search result page"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        }
      },
      "additionalProperties": false,
      "required": ["first", "last"]
    },
    "hitsReturned": {
      "type": "integer",
      "description": "The number of hits returned in this resultset"
    },
    "hitsTotal": {
      "type": "integer",
      "description": "The total number of hits for the search"
    },
    "maxSize": {
      "type": "integer",
      "description": "The max number of hits to provide in the search result"
    },
    "offset": {
      "type": "integer",
      "description": "The current offset in the total resultset (if larger than maxSize)"
    }
  },
  "required": ["$schema", "companies", "hitsReturned", "hitsTotal", "maxSize", "offset", "_links"],
  "additionalProperties": false
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

/companies/{companyId} get head

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

Get a company resource

Request
Response

URI Parameters

Company ID: required (string - minLength: 12 - maxLength: 12 - pattern: ^\d{12}$)
Example:
```
1:100193203
```

Query Parameters

language: (string - default: en - minLength: 2 - maxLength: 2 - pattern: ^[a-z]{2}$)
Example:
```
sv
```

HTTP status code 200

A company resource

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/company.schema.json",
    "$lastModified": "2015-06-01T19:34:09.997Z",
    "name": "Bisnode Marknad AB",
    "country": {
        "name": "Sweden",
        "code": "SE"
    },
    "status": {
        "name": "Active",
        "code": "ST00"
    },
    "type": {
        "name": "Private company",
        "code": "TY50"
    },
    "registrationDate": "1967-10-18",
    "nationalRegistrationNumber": "5561125625",
    "vatNo": "SE556112562501",
    "numberOfWorksites": 7,
    "postalAddress": {
        "villageAddress": "Mall Of Scandinavia",
        "address": "Råsta Strandväg 19 A",
        "co": "c/o Bisnode Sweden",
        "zipcode": "16993",
        "city": "SOLNA",
        "country": {
            "name": "Sweden",
            "code": "SE"
        },
        "county": {
            "name": "Stockholm",
            "code": "GR01"
        },
        "municipality": {
            "name": "Solna",
            "code": "GK0184"
        },
        "SE_Aregion": {
            "code": "GA01",
            "name": "Stockholm/Södertälje"
        }
    },
    "phones": [
        {
            "type": "LeasedLine",
            "number": "+46 87753600",
            "blocked": false
        },
        {
            "type": "Fax",
            "number": "+46 87755088",
            "blocked": false
        }
    ],
    "internet": {
        "emails": [
            {
                "address": "info@bisnode.com",
                "blocked": false
            }
        ],
        "urls": [
            "www.bisnode.com"
        ]
    },
    "legalForm": {
        "name": "Limited company",
        "code": "JF49"
    },
    "economy": {
        "shareCapital": {
            "code": "AK14",
            "name": "1000 - 2000",
            "value": 11767000,
            "currency": "SEK"
        },
        "turnover": {
            "code": "OM07",
            "name": "25000 - 50000",
            "value": 310367000,
            "currency": "SEK"
        },
        "turnoverChange": {
            "code": "NO40",
            "name": "-10% - 0%",
            "rate": -6
        },
        "solvency": {
            "code": "NS60",
            "name": "10% - 25%",
            "rate": 21
        }
    },
    "group": {
        "groupParent": {
            "id": "1:100174190",
            "nationalRegistrationNumber": "5560083585",
            "name": "Ratos AB",
            "country": {
                "name": "Sweden",
                "code": "SE"
            }
        },
        "parent": {
            "id": "1:100846353",
            "nationalRegistrationNumber": "5564573045",
            "name": "Bisnode Sverige AB",
            "country": {
                "name": "Sweden",
                "code": "SE"
            }
        },
        "subsidiaries": [
            {
                "id": "1:102254791",
                "nationalRegistrationNumber": "5568315518",
                "name": "Vendemore Nordic AB",
                "country": {
                    "name": "Sweden",
                    "code": "SE"
                }
            }
        ]
    },
    "business": {
        "activities": {
            "mainActivity": {
                "code": "HG7010",
                "description": "Activities of head offices"
            },
            "subActivities": [
                {
                    "code": "NC4759",
                    "description": "Retail sale of furniture, lighting equipment and other household articles.."
                }
            ],
            "local": {
                "mainActivity": {
                    "code": "HG70109",
                    "description": "Other activities of head offices"
                },
                "subActivities": [
                    {
                        "code": "SN47591",
                        "description": "Retail sale of furniture in specialised stores"
                    }
                ]
            }
        },
        "numberOfEmployees": {
            "name": "100 - 199",
            "code": "AA07"
        },
        "numberOfOfficeEmployees": {
            "name": "100 - 199",
            "code": "KA07"
        }
    },
    "_links": {
        "self": {
            "href": "https://bbc.bisnode.com/v2/companies/1:100193203"
        },
        "worksites": [
            {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200472792"
            },
            {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200138088"
            }
        ],
        "parent": {
            "href": "https://bbc.bisnode.com/v2/companies/1:100846353"
        },
        "groupParent": {
            "href": "https://bbc.bisnode.com/v2/companies/1:100174190"
        }
    },
    "id": "1:100193203",
    "addressSource": "PARAD, 169 93 Solna, Sweden"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Company",
  "type": "object",
  "description": "A Company entity from the Bisnode Business Contacts API",
  "definitions": {
    "country": {
      "type": "object",
      "description": "Container of country code and name",
      "properties": {
        "name": {
          "type": "string",
          "description": "The country name in English"
        },
        "code": {
          "type": "string",
          "description": "The ISO country code",
          "maxLength": 2
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "county": {
      "type": "object",
      "description": "Container of county code and name",
      "properties": {
        "name": {
          "type": "string",
          "description": "The county name in English"
        },
        "code": {
          "type": "string",
          "description": "The county code (local geographic region code)",
          "maxLength": 10
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "municipality": {
      "type": "object",
      "description": "Container of municipality code and name",
      "properties": {
        "name": {
          "type": "string",
          "description": "The Municipality name"
        },
        "code": {
          "type": "string",
          "description": "The Municipality code (local geographic municipality code)",
          "maxLength": 10
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "SE_Aregion": {
      "type": "object",
      "description": "Container of A-region (available in Sweden only)",
      "properties": {
        "name": {
          "type": "string",
          "description": "The A-region name"
        },
        "code": {
          "type": "string",
          "description": "The A-region code (geographic region code)"
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "status": {
      "type": "object",
      "description": "Container of status by name and code",
      "properties": {
        "name": {
          "type": "string",
          "description": "The status in English"
        },
        "code": {
          "type": "string",
          "description": "The status code",
          "maxLength": 10
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "address": {
      "type": "object",
      "properties": {
        "villageAddress": {
          "type": "string",
          "description": "Address line 2 of this company address"
        },
        "address": {
          "type": "string",
          "description": "Address Line 3 of this company address"
        },
        "co": {
          "type": "string",
          "description": "Address Line 1 of this company address"
        },
        "zipcode": {
          "type": "string",
          "description": "The zip code of this company address"
        },
        "city": {
          "type": "string",
          "description": "The city of this company address"
        },
        "country": {
          "$ref": "#/definitions/country"
        },
        "county": {
          "$ref": "#/definitions/county"
        },
        "municipality": {
          "$ref": "#/definitions/municipality"
        },
        "SE_Aregion": {
          "$ref": "#/definitions/SE_Aregion"
        }
      },
      "required": ["city", "country"],
      "additionalProperties": false
    },
    "legalForm": {
      "type": "object",
      "description": "Container of legal form by name and code",
      "properties": {
        "name": {
          "type": "string",
          "description": "The legal form in plain text"
        },
        "code": {
          "type": "string",
          "description": "The (local) legal form code",
          "maxLength": 10
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "phones": {
      "type": "array",
      "items": [{
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
             "description": "The type of this phone"
          },
          "blocked": {
            "type": "boolean",
            "description": "Whether this phone is blocked for direct marketing"
          },
          "number": {
            "type": "string",
            "description": "The phone number"
          }
        },
        "additionalProperties": false
      }]
    },
    "internet": {
      "type": "object",
      "description": "Internet addresses (URL's and emails, etc) related to this company",
      "properties": {
        "emails": {
          "type": "array",
          "description": "List of email addresses related to this company",
          "items": [{
            "type": "object",
            "description": "Contact email address",
            "properties": {
              "address": {
                "type": "string",
                "description": "The email address"
              },
              "blocked": {
                "type": "boolean",
                "description": "Whether this email address is blocked for direct marketing"
              }
            },
            "additionalProperties": false
          }]
        },
        "urls": {
          "type": "array",
          "description": "List of URLs related to this company",
          "items": {
            "type": "string",
            "description": "Company URL"
          }
        }
      },
      "additionalProperties": false
    },
    "shareCapital": {
      "type": "object",
      "description": "Container of shareCapital by name and code (only available in Sweden)",
      "properties": {
        "name": {
          "type": "string",
          "description": "The share capital range. The currency is specified in the nameCurrency field."
        },
        "nameCurrency": {
          "type": "string",
          "description": "The currency used in the name field"
        },
        "code": {
          "type": "string",
          "description": "The share capital code",
          "minLength": 4,
          "maxLength": 4
        },
        "value": {
          "type": "integer",
          "description": "The numeric share capital value. The currency is specified in the currency field."
        },
        "currency": {
          "type": "string",
          "description": "The currency used in the value field"
        }
      },
      "additionalProperties": false
    },
    "turnover": {
      "type": "object",
      "description": "Container of turnover by name and code",
      "properties": {
        "name": {
          "type": "string",
          "description": "The turnover range. The currency is specified in the nameCurrency field."
        },
        "nameCurrency": {
          "type": "string",
          "description": "The currency used in the name field"
        },
        "code": {
          "type": "string",
          "description": "The turnover code",
          "minLength": 4,
          "maxLength": 4
        },
        "value": {
          "type": "integer",
          "description": "The numeric turnover value. The currency is specified in the currency field."
        },
        "currency": {
          "type": "string",
          "description": "The currency used in the value field"
        }
      },
      "additionalProperties": false
    },
    "turnoverChange": {
      "type": "object",
      "description": "Container of turnover change by name, code and rate (only available in Sweden)",
      "properties": {
        "name": {
          "type": "string",
          "description": "The turnover change compared to previous year as a percentage range"
        },
        "code": {
          "type": "string",
          "description": "The turnover change code",
          "minLength": 4,
          "maxLength": 4
        },
        "rate": {
          "type": "integer",
          "description": "The turnover change in percent"
        }
      },
      "additionalProperties": false
    },
    "solvency": {
      "type": "object",
      "description": "Container of solvency by name, code and rate (only available in Sweden)",
      "properties": {
        "name": {
          "type": "string",
          "description": "The solvency as a percentage range"
        },
        "code": {
          "type": "string",
          "description": "The solvency code",
          "minLength": 4,
          "maxLength": 4
        },
        "rate": {
          "type": "integer",
          "description": "The solvency in percent"
        }
      },
      "additionalProperties": false
    },
    "economy": {
      "type": "object",
      "description": "Economic data on this company",
      "properties": {
        "shareCapital": {
          "$ref": "#/definitions/shareCapital"
        },
        "turnover": {
          "$ref": "#/definitions/turnover"
        },
        "turnoverChange": {
          "$ref": "#/definitions/turnoverChange"
        },
        "solvency": {
          "$ref": "#/definitions/solvency"
        }
      },
      "additionalProperties": false
    },
    "groupInformation": {
      "type": "object",
      "description": "Container of groupParent/parent/subsidiaries by id, nationalRegistrationNumber, name and country (only available in the Nordic countries)",
      "properties": {
        "id": {
          "type": "string",
          "description": "The unique identifier of this company entity"
        },
        "nationalRegistrationNumber": {
          "type": "string",
          "description": "Company registration number"
        },
        "name": {
          "type": "string",
          "description": "The Legal Name"
        },
        "country": {
          "$ref": "#/definitions/country"
        }
      },
      "additionalProperties": false
    },
    "businessActivity": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "The code of this activity",
          "maxLength": 10
        },
        "description": {
          "type": "string",
          "description": "Description of this activity"
        }
      },
      "additionalProperties": false
    },
    "businessActivities": {
      "type": "object",
      "properties": {
        "mainActivity": {
          "$ref": "#/definitions/businessActivity"
        },
        "subActivities": {
          "type": "array",
          "items": [
            {
              "$ref": "#/definitions/businessActivity"
            }
          ]
        },
        "local": {
          "$ref": "#/definitions/localBusinessActivities"
        }
      },
      "additionalProperties": false
    },
    "localBusinessActivities": {
      "type": "object",
      "description": "Local business activity codes. Note that local sub-activities are not available in the Baltic countries and Greece",
      "properties": {
        "mainActivity": {
          "$ref": "#/definitions/businessActivity"
        },
        "subActivities": {
          "type": "array",
          "items": [
            {
              "$ref": "#/definitions/businessActivity"
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "business": {
      "type": "object",
      "description": "Data concerning the activities of this business",
      "properties": {
        "activities": {
          "$ref": "#/definitions/businessActivities"
        },
        "numberOfEmployees": {
          "type": "object",
          "description": "Number of employees",
          "properties": {
            "name": {
              "type": "string",
              "description": "Textual representation in range format (i.e. 100 - 199, etc)"
            },
            "code": {
              "type": "string",
              "description": "The code representing the number of employees",
              "maxLength": 10
            }
          },
          "additionalProperties": false
        },
        "numberOfOfficeEmployees": {
          "type": "object",
          "description": "Number of office employees (only available in Sweden)",
          "properties": {
            "name": {
              "type": "string",
              "description": "Textual representation in range format (i.e. 100 - 199, etc)"
            },
            "code": {
              "type": "string",
              "description": "The code representing the number of employees",
              "maxLength": 10
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "links": {
      "type": "object",
      "description": "Links to other entities related to this company",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL reference to this entity"
            }
          }
        },
        "worksites": {
          "type": "array",
          "description": "A list of worksites related to this company",
          "items": {
            "type": "object",
            "properties": {
              "href": {
                "type": "string",
                "description": "The URL reference to this worksite"
              }
            }
          }
        },
        "employments": {
          "type": "array",
          "description": "A list of employments related to this company",
          "items": {
            "type": "object",
            "properties": {
              "href": {
                "type": "string",
                "description": "The URL reference to this employment"
              }
            }
          }
        },
        "parent": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL reference to the parent company, if any"
            }
          }
        },
        "groupParent": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL reference to the group parent company, if any"
            }
          }
        }
      },
      "required": ["self"],
      "additionalProperties": false
    },
    "subsidiaries": {
      "type": "array",
      "description": "A list of subsidiaries",
      "items": {
        "$ref": "#/definitions/groupInformation"
      }
    }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "$lastModified": {
      "type": "string",
      "description": "Date and time when this resource was last updated. Use this string for queries to /companies/changes."
    },
    "id": {
      "type": "string",
      "description": "The unique identifier of this company entity",
      "pattern": "\\d{1,3}:\\d{9}"
    },
    "registrationDate": {
      "type": "string",
      "description": "Company registrationDate"
    },
    "nationalRegistrationNumber": {
      "type": "string",
      "description": "Company registration number",
      "maxLength": 24
    },
    "vatNo": {
      "type": "string",
      "description": "VAT number of this company",
      "maxLength": 30
    },
    "numberOfWorksites": {
      "type": "integer",
      "description": "number of worksites for this company"
    },
    "name": {
      "type": "string",
      "description": "The legal name of this company",
      "maxLength": 500
    },
    "country": {
      "$ref": "#/definitions/country"
    },
    "status": {
      "$ref": "#/definitions/status"
    },
    "internet": {
      "$ref": "#/definitions/internet"
    },
    "business": {
      "$ref": "#/definitions/business"
    },
    "economy": {
      "$ref": "#/definitions/economy"
    },
    "type": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Type of company"
        },
        "code": {
          "type": "string",
          "description": "Code of company type",
          "maxLength": 10
        }
      },
      "additionalProperties": false
    },
    "postalAddress": {
      "$ref": "#/definitions/address"
    },
    "phones": {
      "$ref": "#/definitions/phones"
    },
    "legalForm": {
      "$ref": "#/definitions/legalForm"
    },
    "group": {
      "type": "object",
      "properties": {
        "groupParent": {
          "$ref": "#/definitions/groupInformation"
        },
        "parent": {
          "$ref": "#/definitions/groupInformation"
        },
        "subsidiaries": {
          "$ref": "#/definitions/subsidiaries"
        }
      },
      "additionalProperties": false
    },
    "analytics": {
      "type": "object",
      "description": "Analytics variables provided by Bisnode",
      "properties": {
        "economicPerformance": {
          "type": "number",
          "description": "The company's economic performance. Value ranging from 1 to 5, where 1 is the best and 5 is the worst.",
          "minimum": 1,
          "maximum": 5
        },
        "employmentPrediction": {
          "type": "number",
          "description": "The company's employment prediction. Value ranging from 1 to 5, where 1 is the best and 5 is the worst.",
          "minimum": 1,
          "maximum": 5
        },
        "growthPrediction": {
          "type": "number",
          "description": "The company's growth prediction. Value ranging from 1 to 5, where 1 is the best and 5 is the worst.",
          "minimum": 1,
          "maximum": 5
        },
        "indicativeRating": {
          "type": "object",
          "description": "The company's indicative rating",
          "properties": {
            "name": {
              "type": "string",
              "description": "Textual representation of the indicative rating (i.e. High, Medium, Low, etc)"
            },
            "code": {
              "type": "string",
              "description": "Code of the indicative rating",
              "maxLength": 10
            }
          }
        }
      }
    },
    "addressSource": {
      "type": "string",
      "description": "Source of the address information"
    },
    "_links": {
      "$ref": "#/definitions/links"
    }
  },
  "required": ["$schema", "$lastModified", "id", "name", "country", "status", "type"],
  "additionalProperties": false
}

HTTP status code 403

Each user of the API has a quota limit. The limit is defined as the amount of unique entities allowed to be fetched per year. Once the quota has been reached the user can still fetch any entity already fetched within the quota but is not allowed to fetch any new entities. The current quota limit status is reflected by response headers from the API:

X-Quota-Limit: The yearly quota.
X-Quota-Remaining: Remaining part of the yearly quota.

Headers

X-Quota-Limit: (integer)
X-Quota-Remaining: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Quota limit of 150000 unique entities exceeded. You can still retrieve any entity that you have previously retrieved during the quota period as only unique entities count towards the quota."
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

See description of GET request for this endpoint

Request
Response

URI Parameters

Company ID: required (string - minLength: 12 - maxLength: 12 - pattern: ^\d{12}$)
Example:
```
1:100193203
```

HTTP status code 200

Same as GET but with empty response body

HTTP status code 403

X-Quota-Limit: The yearly quota.
X-Quota-Remaining: Remaining part of the yearly quota.

Headers

X-Quota-Limit: (integer)
X-Quota-Remaining: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Quota limit of 150000 unique entities exceeded. You can still retrieve any entity that you have previously retrieved during the quota period as only unique entities count towards the quota."
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

/companies/changes post

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.

Request
Response

Body

Type: application/json

Example:

[
  {
    "companyId": "110:103793981",
    "since": "2014-01-01T00:00:00.000Z"
  },
  {
    "companyId": "110:103793982",
    "since": "2013-01-01T00:00:00.000Z"
  },
  {
    "companyId": "110:103793983",
    "since": "2015-01-01T00:00:00.000Z"
  }
]

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Company changes request",
  "type": "array",
  "items": [
    {
      "type": "object",
      "properties": {
        "companyId": {
          "description": "A company ID (provided by Bisnode)",
          "type": "string"
        },
        "since": {
          "description": "DateTime saying from how far back you want changes. (ISO-8601 extended offset date-time format, 2015-03-10T13:02:51.692+01:00)",
          "type": "string"
        }
      },
      "required": [
        "companyId",
        "since"
      ],
      "additionalProperties": false
    }
  ]
}

HTTP status code 200

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/company-changes-response.schema.json",
    "changes": [
        {
            "companyId": "110:103793981",
            "changeType": "updated",
            "changedFields": [],
            "addedAndRemovedWorksites": [
                {
                    "type": "removal",
                    "worksiteId": "110:204396648",
                    "at": "2014-02-13T12:05:16.565Z"
                }
            ]
        },
        {
            "companyId": "110:103793983",
            "changeType": "unchanged",
            "changedFields": [],
            "addedAndRemovedWorksites": []
        },
        {
            "companyId": "110:103793982",
            "changeType": "updated",
            "changedFields": [
                {
                    "jsonPath": "$.postalAddress",
                    "lastModifiedAt": "2015-03-23T11:02:32.527Z"
                },
                {
                    "jsonPath": "$.name",
                    "lastModifiedAt": "2014-10-10T00:11:28.672Z"
                }
            ],
            "addedAndRemovedWorksites": [
                {
                    "type": "addition",
                    "worksiteId": "110:212443401",
                    "at": "2015-03-23T11:02:32.561Z"
                },
                {
                    "type": "removal",
                    "worksiteId": "110:205360287",
                    "at": "2015-03-23T11:02:32.575Z"
                }
            ]
        }
    ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Company changes response",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "changes": {
      "type": "array",
      "items": {
        "title": "Company Change Entry",
        "type": "object",
        "properties": {
          "companyId": {
            "description": "A company ID (provided by Bisnode)",
            "type": "string"
          },
          "changeType": {
            "description": "The type of change.",
            "enum": [
              "unchanged",
              "updated",
              "removed"
            ]
          },
          "changedFields": {
            "description": "A list of all changed fields",
            "type": "array",
            "items": {
              "title": "Changed field",
              "type": "object",
              "properties": {
                "jsonPath": {
                  "description": "The JSON path in the company document for the affected field",
                  "type": "string"
                },
                "lastModifiedAt": {
                  "description": "The date and time when this field was last changed (ISO-8601 extended offset date-time format, 2015-03-10T13:02:51.692+01:00)",
                  "type": "string"
                }
              },
              "required": [
                "jsonPath",
                "lastModifiedAt"
              ],
              "additionalProperties": false
            }
          },
          "addedAndRemovedWorksites": {
            "type": "array",
            "items": {
              "title": "Added or removed worksites",
              "type": "object",
              "properties": {
                "type": {
                  "description": "Type of change",
                  "enum": [
                    "addition",
                    "removal"
                  ]
                },
                "worksiteId": {
                  "description": "A worksite ID (provided by Bisnode)",
                  "type": "string"
                },
                "at": {
                  "description": "Date and time when this Worksite has been added or removed",
                  "type": "string"
                }
              },
              "required": [
                "type",
                "worksiteId",
                "at"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "companyId",
          "changeType",
          "changedFields",
          "addedAndRemovedWorksites"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "$schema",
    "changes"
  ]
}

Worksites

Search, download and query changes for worksites

/worksites get

get

Search/filter by provided parameters

Request
Response

Query Parameters

maxSize: (integer - default: 10 - maximum: 10000)
Max number of results to provide in each resultset
Example:
```
20
```
offset: (integer - maximum: 10000)
The current offset in the total result set hit count (totalHits in the search result data)
Example:
```
10
```
fulltext: (string)
Search within all fields at once, for example company name and city (see example below)
Example:
```
Bisnode Stockholm
```
country: (string - pattern: ^[A-Za-z]{2}$)
ISO country code.
Available country codes may be retrieved through the /countries endpoint.
Example:
```
DE
```
generalName: (string)
Search by worksite name or the legal name of the associated company
companyLegalName: (string)
Search by the legal name of the associated company
worksiteGeneralAddress: (string)
Search by postal address and visiting address
worksiteGeneralCity: (string)
Search by worksite city location
worksiteGeneralZipcode: (string)
Search by worksite zip code
phone: (string)
Search by worksite phone numbers.
Example:
```
004412345678
```
worksiteType: (string)
Search by type of worksite
Example:
```
TY10
```
worksiteStatus: (string)
Search by status of the worksite
Example:
```
ST00
```
email: (string)
Search by the email addresses of this worksite's associated contacts
worksiteNumber: (string)
Search by worksite number
companyNumber: (string)
Search by company registration number or company VAT number
contactName: (string)
Search by first or last names of associated contacts
contactFirstName: (string)
Search by first name of associated contacts
contactLastName: (string)
Search by last name of associated contacts

HTTP status code 200

A worksite-search resource

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/worksite-search.schema.json",
    "worksites": [{
        "name": "Bisnode AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Rosenborgsgatan 4",
            "city": "SOLNA"
        },
        "postalAddress": {
            "city": "SOLNA"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Head Office",
            "code": "TY10"
        },
        "numberOfContacts": 8,
        "company": {
            "id": "1:100277670",
            "legalName": "Bisnode AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200099336"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100277670"
            }
        },
        "id": "1:200099336"
    }, {
        "name": "Bisnode Kredit AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Vigelsjövägen 3",
            "city": "NORRTÄLJE"
        },
        "postalAddress": {
            "city": "NORRTÄLJE"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Branch office",
            "code": "TY20"
        },
        "numberOfContacts": 0,
        "company": {
            "id": "1:100357443",
            "legalName": "Bisnode Kredit AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:202262681"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100357443"
            }
        },
        "id": "1:202262681"
    }, {
        "name": "Bisnode Information AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Vasagatan 12",
            "city": "UMEÅ"
        },
        "postalAddress": {
            "city": "UMEÅ"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Branch office",
            "code": "TY20"
        },
        "numberOfContacts": 0,
        "company": {
            "id": "1:100325911",
            "legalName": "Bisnode Information AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:202341144"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100325911"
            }
        },
        "id": "1:202341144"
    }, {
        "name": "Bisnode Kredit AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Kilsgatan 4",
            "city": "GÖTEBORG"
        },
        "postalAddress": {
            "city": "GÖTEBORG"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Branch office",
            "code": "TY20"
        },
        "numberOfContacts": 9,
        "company": {
            "id": "1:100357443",
            "legalName": "Bisnode Kredit AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200648080"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100357443"
            }
        },
        "id": "1:200648080"
    }, {
        "name": "Bisnode Kredit AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Storgatan 25",
            "city": "ÖSTERSUND"
        },
        "postalAddress": {
            "city": "ÖSTERSUND"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Branch office",
            "code": "TY20"
        },
        "numberOfContacts": 0,
        "company": {
            "id": "1:100357443",
            "legalName": "Bisnode Kredit AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200005468"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100357443"
            }
        },
        "id": "1:200005468"
    }, {
        "name": "Bisnode Kredit AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Södergatan 14",
            "city": "MALMÖ"
        },
        "postalAddress": {
            "city": "MALMÖ"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Branch office",
            "code": "TY20"
        },
        "numberOfContacts": 0,
        "company": {
            "id": "1:100357443",
            "legalName": "Bisnode Kredit AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:201858236"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100357443"
            }
        },
        "id": "1:201858236"
    }, {
        "name": "Bisnode Kredit AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Rosenborgsgatan 4",
            "city": "SOLNA"
        },
        "postalAddress": {
            "city": "SOLNA"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Head Office",
            "code": "TY10"
        },
        "numberOfContacts": 7,
        "company": {
            "id": "1:100357443",
            "legalName": "Bisnode Kredit AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200719709"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100357443"
            }
        },
        "id": "1:200719709"
    }, {
        "name": "Bisnode Marknad AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Prästgatan 31 B",
            "city": "ÖSTERSUND"
        },
        "postalAddress": {
            "city": "ÖSTERSUND"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Branch office",
            "code": "TY20"
        },
        "numberOfContacts": 1,
        "company": {
            "id": "1:100193203",
            "legalName": "Bisnode Marknad AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:201723107"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100193203"
            }
        },
        "id": "1:201723107"
    }, {
        "name": "Bisnode Marknad AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Kilsgatan 4",
            "city": "GÖTEBORG"
        },
        "postalAddress": {
            "city": "GÖTEBORG"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Branch office",
            "code": "TY20"
        },
        "numberOfContacts": 26,
        "company": {
            "id": "1:100193203",
            "legalName": "Bisnode Marknad AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200472792"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100193203"
            }
        },
        "id": "1:200472792"
    }, {
        "name": "Bisnode Marknad AB",
        "country": "SE",
        "visitingAddress": {
            "address": "Rosenborgsgatan 4-6",
            "city": "SOLNA"
        },
        "postalAddress": {
            "city": "SOLNA"
        },
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "type": {
            "name": "Head Office",
            "code": "TY10"
        },
        "numberOfContacts": 40,
        "company": {
            "id": "1:100193203",
            "legalName": "Bisnode Marknad AB"
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200001039"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100193203"
            }
        },
        "id": "1:200001039"
    }],
    "maxSize": 10,
    "offset": 0,
    "hitsReturned": 10,
    "hitsTotal": 23,
    "_links": {
        "self": {
            "href": "https://bbc.bisnode.com/v2/worksites?generalName=Bisnode&worksiteStatus=00&country=SE"
        },
        "first": {
            "href": "https://bbc.bisnode.com/v2/worksites?country=SE&generalName=Bisnode&worksiteStatus=00"
        },
        "last": {
            "href": "https://bbc.bisnode.com/v2/worksites?country=SE&generalName=Bisnode&worksiteStatus=00&offset=20"
        },
        "next": {
            "href": "https://bbc.bisnode.com/v2/worksites?country=SE&generalName=Bisnode&worksiteStatus=00&offset=10"
        }
    }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Worksite search result",
  "type": "object",
  "description": "Worksite search result schema from the Bisnode Business Contacts API",
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "address": {
          "type": "string",
          "description": "Street address"
        },
        "city": {
          "type": "string",
          "description": "City"
        }
      },
      "additionalProperties": false
    },
    "worksite": {
      "type": "object",
      "description": "A worksite search result entity",
      "properties": {
        "name": {
          "type": "string",
          "description": "The general name of the company associated with this worksite"
        },
        "country": {
          "type": "string",
          "description": "The ISO country code of this worksite's country"
        },
        "id": {
          "type": "string",
          "description": "ID of worksite"
        },
        "company": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "ID of the company this worksite belongs to"
            },
            "legalName": {
              "type": "string",
              "description": "The legal name of the company associated with this worksite"
            }
          },
          "additionalProperties": false,
          "required": ["id"]
        },
        "type": {
          "type": "object",
          "description": "The type of worksite (code and name)",
          "properties": {
            "code": {
              "type": "string",
              "description": "The type of worksite represented as a code"
            },
            "name": {
              "type": "string",
              "description": "The name or description of the worksite type"
            }
          },
          "additionalProperties": false,
          "required": ["code", "name"]
        },
        "status": {
          "type": "object",
          "description": "The status of the worksite (code and name)",
          "properties": {
            "code": {
              "type": "string",
              "description": "The status of the worksite represented as a code"
            },
            "name": {
              "type": "string",
              "description": "The name or description of the worksite status"
            }
          },
          "additionalProperties": false,
          "required": ["code", "name"]
        },
        "numberOfContacts": {
          "type": "integer",
          "description": "The number of contacts (employments) connected to this worksite"
        },
        "visitingAddress": {
          "$ref": "#/definitions/address"
        },
        "postalAddress": {
          "$ref": "#/definitions/address"
        },
        "_links": {
          "type": "object",
          "properties": {
            "worksite": {
              "type": "object",
              "description": "URL for downloading this search hit",
              "properties": {
                "href": {
                  "type": "string"
                }
              }
            },
            "company": {
              "type": "object",
              "description": "URL for downloading the company of this search hit",
              "properties": {
                "href": {
                  "type": "string"
                }
              }
            }
          },
          "required": ["company", "worksite"],
          "additionalProperties": false
        }
      },
      "required": ["id", "name", "country", "_links"],
      "additionalProperties": false
    }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "worksites": {
      "type": "array",
      "description": "A list of worksite search results",
      "items": {
        "$ref": "#/definitions/worksite"
      }
    },
    "_links": {
      "type": "object",
      "description": "Links for navigating the search result. Links of type 'first' and 'last' will always be present while 'previous' and 'next' only will be available when applicable.",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL of the current search result"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the previous search result page (if avaialable)"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the next search result page (if avaialable)"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "first": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the first search result page"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "last": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the last search result page"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        }
      },
      "additionalProperties": false,
      "required": ["first", "last"]
    },
    "hitsReturned": {
      "type": "integer",
      "description": "The number of hits returned in this resultset"
    },
    "hitsTotal": {
      "type": "integer",
      "description": "The total number of hits for the search"
    },
    "maxSize": {
      "type": "integer",
      "description": "The max number of hits to provide in the search result"
    },
    "offset": {
      "type": "integer",
      "description": "The current offset in the total resultset (if larger than maxSize)"
    }
  },
  "required": ["$schema", "worksites", "hitsReturned", "hitsTotal", "maxSize", "offset", "_links"],
  "additionalProperties": false
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

/worksites/{worksiteId} get head

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 a worksite resource

Request
Response

URI Parameters

Worksite ID: required (string - minLength: 12 - maxLength: 12 - pattern: ^\d{12}$)
Example:
```
1:200001039
```

Query Parameters

language: (string - default: en - minLength: 2 - maxLength: 2 - pattern: ^[a-z]{2}$)
Example:
```
sv
```

HTTP status code 200

A worksite resource

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/worksite.schema.json",
    "$lastModified": "2015-05-07T01:23:54.556Z",
    "name": "Bisnode Marknad AB ",
    "country": {
        "name": "Sweden",
        "code": "SE"
    },
    "status": {
        "name": "Active",
        "code": "ST00"
    },
    "type": {
        "name": "Head office",
        "code": "TY10"
    },
    "department": "Economy department",
    "officialWorksiteNumber": "19553817",
    "postalAddress": {
        "villageAddress": "Mall Of Scandinavia",
        "address": "Råsta Strandväg 19 A",
        "co": "c/o Bisnode Sweden",
        "zipcode": "16993",
        "city": "SOLNA",
        "country": {
            "name": "Sweden",
            "code": "SE"
        },
        "county": {
            "name": "Stockholm",
            "code": "GR01"
        },
        "municipality": {
            "name": "Solna",
            "code": "GK0184"
        },
        "SE_Aregion" : {
            "code": "GA01",
            "name": "Stockholm/Södertälje"
        }
    },
    "visitAddress": {
        "villageAddress": "Mall Of Scandinavia",
        "address": "Råsta Strandväg 19 A",
        "co": "c/o Bisnode Sweden",
        "zipcode": "16974",
        "city": "SOLNA",
        "country": {
            "name": "Sweden",
            "code": "SE"
        },
        "county": {
            "name": "Stockholm",
            "code": "GR01"
        },
        "SE_Aregion" : {
            "code": "GA01",
            "name": "Stockholm/Södertälje"
        }
    },
    "company": {
        "nationalRegistrationNumber": "5561125625",
        "id": "1:100193203"
    },
    "phones": [
        {
            "type": "LeasedLine",
            "number": "+46 87753600",
            "blocked": false
        },
        {
            "type": "Fax",
            "number": "+46 87755088",
            "blocked": false
        }
    ],
    "internet": {
        "emails": [
            {
                "address": "info@bisnode.com",
                "blocked": false
            }
        ],
        "urls": [
            "www.bisnode.com"
        ]
    },
    "business": {
        "activities": {
            "mainActivity": {
                "code": "HG7311",
                "description": "Advertising agencies"
            },
            "subActivities": [
                {
                    "code": "NC4791",
                    "description": "Retail sale via mail order houses or via Internet"
                }
            ],
            "local": {
                "mainActivity": {
                    "code": "HG0000900",
                    "description": "Unknown"
                },
                "subActivities": [
                    {
                        "code": "SN73112",
                        "description": "Delivery of advertising material"
                    }
                ]
            }
        },
        "mainCommunicationLanguage": {
            "name": "Swedish",
            "code": "SV"
        },
        "numberOfEmployees": {
            "name": "50 - 99",
            "code": "AA06"
        },
        "numberOfOfficeEmployees": {
            "name": "Unknown",
            "code": "KA99"
        },
        "trade": {
            "importing": true,
            "exporting": true
        }
    },
    "_links":{
        "self":{
            "href": "https://bbc.bisnode.com/v2/worksites/1:200001039"
        },
        "company":{
            "href": "https://bbc.bisnode.com/v2/companies/1:100193203"
        },
        "employments":[
            {
                "href": "https://bbc.bisnode.com/v2/employments/1:403813001"
            },
            {
                "href": "https://bbc.bisnode.com/v2/employments/1:402909928"
            }
        ]
    },
    "id": "1:200001039",
    "addressSource": "PARAD, 169 93 Solna, Sweden"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Worksite",
  "type": "object",
  "description": "A worksite entity from the Bisnode Business Contacts API",
  "definitions": {
    "country": {
      "type": "object",
      "description": "Container of country code and name",
      "properties": {
        "name": {
          "type": "string",
          "description": "The country name in English"
        },
        "code": {
          "type": "string",
          "description": "The ISO country code",
          "maxLength": 2
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "county": {
      "type": "object",
      "description": "Container of county code and name",
      "properties": {
        "name": {
          "type": "string",
          "description": "The county name in English"
        },
        "code": {
          "type": "string",
          "description": "The county code (geographic region code)"
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "municipality": {
      "type": "object",
      "description": "Container of municipality code and name",
      "properties": {
        "name": {
          "type": "string",
          "description": "The municipality name in English"
        },
        "code": {
          "type": "string",
          "description": "The municipality code (geographic region code)"
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "SE_Aregion": {
      "type": "object",
      "description": "Container of A-region (available in Sweden only)",
      "properties": {
        "name": {
          "type": "string",
          "description": "The A-region name"
        },
        "code": {
          "type": "string",
          "description": "The A-region code (geographic region code)"
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "status": {
      "type": "object",
      "description": "Container of status by name and code",
      "properties": {
        "name": {
          "type": "string",
          "description": "The status in English"
        },
        "code": {
          "type": "string",
          "description": "The status code"
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "address": {
      "type": "object",
      "properties": {
        "villageAddress": {
          "type": "string",
          "description": "Address Line 2 of this worksite address"
        },
        "address": {
          "type": "string",
          "description": "Address Line 3 of this worksite address"
        },
        "co": {
          "type": "string",
          "description": "Address Line 1 of this worksite address"
        },
        "zipcode": {
          "type": "string",
          "description": "The zip code of this worksite address"
        },
        "city": {
          "type": "string",
          "description": "The city of this worksite address"
        },
        "country": {
          "$ref": "#/definitions/country"
        },
        "county": {
          "$ref": "#/definitions/county"
        },
        "municipality": {
          "$ref": "#/definitions/municipality"
        },
        "SE_Aregion": {
            "$ref": "#/definitions/SE_Aregion"
        }
      },
      "required": ["country"],
      "additionalProperties": false
    },
    "company": {
      "type": "object",
      "description": "Data describing this worksite's parent company",
      "properties": {
        "nationalRegistrationNumber": {
          "type": "string",
          "description": "Company registration number"
        },
        "id": {
          "type": "string",
          "description": "A unique company id (provided by Bisnode)"
        }
      },
      "additionalProperties": false
    },
    "phones": {
      "description": "List of phone numbers connected to this entity",
      "type": "array",
      "items": [{
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of this phone"
          },
          "blocked": {
            "type": "boolean",
            "description": "Whether this phone is blocked for direct marketing"
          },
          "number": {
            "type": "string",
            "description": "The phone number"
          }
        },
        "additionalProperties": false
      }]
    },
    "internet": {
      "type": "object",
      "description": "Internet addresses (url's and emails, etc) related to this worksite",
      "properties": {
        "emails": {
          "type": "array",
          "description": "List of e-mail addresses related to this worksite",
          "items": [{
            "type": "object",
            "description": "Contact e-mail address",
            "properties": {
              "address": {
                "type": "string",
                "description": "The e-mail address"
              },
              "blocked": {
                "type": "boolean",
                "description": "Whether this e-mail address is blocked for direct marketing"
              }
            },
            "additionalProperties": false
          }]
        },
        "urls": {
          "type": "array",
          "description": "List of URLs related to this worksite",
          "items": {
            "type": "string",
            "description": "Worksite URL"
          }
        }
      },
      "additionalProperties": false
    },
    "businessActivity": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "The code of this activity"
        },
        "description": {
          "type": "string",
          "description": "Description of this activity"
        }
      },
      "additionalProperties": false
    },
    "businessActivities": {
      "type": "object",
      "properties": {
        "mainActivity": {
          "$ref": "#/definitions/businessActivity"
        },
        "subActivities": {
          "type": "array",
          "items": [
            {
              "$ref": "#/definitions/businessActivity"
            }
          ]
        },
        "local": {
          "$ref": "#/definitions/localBusinessActivities"
        }
      },
      "additionalProperties": false
    },
    "localBusinessActivities": {
      "type": "object",
      "description": "Local business activity codes",
      "properties": {
        "mainActivity": {
          "$ref": "#/definitions/businessActivity"
        },
        "subActivities": {
          "type": "array",
          "items": [
            {
              "$ref": "#/definitions/businessActivity"
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "business": {
      "type": "object",
      "description": "Data concerning the activities of this worksite",
      "properties": {
        "activities": {
          "$ref": "#/definitions/businessActivities"
        },
        "mainCommunicationLanguage": {
          "type": "object",
          "description": "Communication language for this worksite",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the language, e.g., German"
            },
            "code": {
              "type": "string",
              "description": "The language code, e.g., DE",
              "maxLength": 10
            }
          },
          "additionalProperties": false
        },
        "numberOfEmployees": {
          "type": "object",
          "description": "Number of employees",
          "properties": {
            "name": {
              "type": "string",
              "description": "Textual representation in range format (i.e. 100 - 199, etc)"
            },
            "code": {
              "type": "string",
              "description": "The code representing the number of employees",
              "maxLength": 10
            }
          },
          "additionalProperties": false
        },
        "numberOfOfficeEmployees": {
          "type": "object",
          "description": "Number of office employees (only available in Sweden)",
          "properties": {
            "name": {
              "type": "string",
              "description": "Textual representation in range format (i.e. 100 - 199, etc)"
            },
            "code": {
              "type": "string",
              "description": "The code representing the number of employees",
              "maxLength": 10
            }
          },
          "additionalProperties": false
        },
        "trade": {
          "type": "object",
            "description": "Import and export information",
            "properties": {
                "importing": {
                    "type": "boolean",
                    "description": "True if this worksite is an importer"
                },
                "exporting": {
                    "type": "boolean",
                    "description": "True if this worksite is an exporter"
                }
            }
        }
      },
      "additionalProperties": false
    },
    "links": {
      "type": "object",
      "description": "Links to other entities related to this worksite",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL reference to this entity"
            }
          },
          "additionalProperties": false
        },
        "company": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL reference to this worksite's related company"
            }
          },
          "additionalProperties": false
        },
        "employments": {
          "type": "array",
          "description": "A list of employments related to this worksite",
          "items": {
            "type": "object",
            "properties": {
              "href": {
                "type": "string",
                "description": "The URL reference to this employment"
              }
            }
          }
        }
      },
      "required": ["self", "company"]
    }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "$lastModified": {
      "type": "string",
      "description": "Date and time when this resource was last updated. Use this string for queries to /worksites/changes."
    },
    "id": {
      "type": "string",
      "description": "The unique identifier of this worksite entity",
      "pattern": "\\d{1,3}:\\d{9}"
    },
    "name": {
      "type": "string",
      "description": "The company name"
    },
    "country": {
      "$ref": "#/definitions/country"
    },
    "status": {
      "$ref": "#/definitions/status"
    },
    "type": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of this worksite type"
        },
        "code": {
          "type": "string",
          "description": "The code of this worksite type"
        }
      },
      "additionalProperties": false
    },
    "company": {
      "$ref": "#/definitions/company"
    },
    "department": {
      "type": "string",
      "description": "The department name, if any"
    },
    "officialWorksiteNumber": {
      "type": "string"
    },
    "postalAddress": {
      "$ref": "#/definitions/address"
    },
    "visitAddress": {
      "$ref": "#/definitions/address"
    },
    "phones": {
      "$ref": "#/definitions/phones"
    },
    "internet": {
      "$ref": "#/definitions/internet"
    },
    "business": {
      "$ref": "#/definitions/business"
    },
    "addressSource": {
      "type": "string",
      "description": "Source of the address information"
    },
    "_links": {
      "$ref": "#/definitions/links"
    }
  },
  "required": ["$schema", "$lastModified", "id", "name", "country", "status", "type"],
  "additionalProperties": false
}

HTTP status code 403

X-Quota-Limit: The yearly quota.
X-Quota-Remaining: Remaining part of the yearly quota.

Headers

X-Quota-Limit: (integer)
X-Quota-Remaining: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Quota limit of 150000 unique entities exceeded. You can still retrieve any entity that you have previously retrieved during the quota period as only unique entities count towards the quota."
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

See description of GET request for this endpoint

Request
Response

URI Parameters

Worksite ID: required (string - minLength: 12 - maxLength: 12 - pattern: ^\d{12}$)
Example:
```
1:200001039
```

HTTP status code 200

Same as GET but with empty response body

HTTP status code 403

X-Quota-Limit: The yearly quota.
X-Quota-Remaining: Remaining part of the yearly quota.

Headers

X-Quota-Limit: (integer)
X-Quota-Remaining: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Quota limit of 150000 unique entities exceeded. You can still retrieve any entity that you have previously retrieved during the quota period as only unique entities count towards the quota."
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

/worksites/changes post

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.

Request
Response

Body

Type: application/json

Example:

[
  {
    "worksiteId": "110:203793981",
    "since": "2014-01-01T00:00:00.000Z"
  },
  {
    "worksiteId": "110:203793982",
    "since": "2013-01-01T00:00:00.000Z"
  },
  {
    "worksiteId": "110:203793983",
    "since": "2015-01-01T00:00:00.000Z"
  }
]

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Worksite changes request",
  "type": "array",
  "items": [
    {
      "type": "object",
      "properties": {
        "worksiteId": {
          "description": "A worksite ID (provided by Bisnode)",
          "type": "string"
        },
        "since": {
          "description": "DateTime saying from how far back you want changes. (ISO-8601 extended offset date-time format, 2015-03-10T13:02:51.692+01:00)",
          "type": "string"
        }
      },
      "required": [
        "worksiteId",
        "since"
      ],
      "additionalProperties": false
    }
  ]
}

HTTP status code 200

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/worksite-changes-response.schema.json",
    "changes": [
        {
            "worksiteId": "110:203793981",
            "changeType": "updated",
            "changedFields": [],
            "addedAndRemovedEmployments": [
                {
                    "type": "removal",
                    "employmentId": "110:404396648",
                    "at": "2014-02-13T12:05:16.565Z"
                }
            ]
        },
        {
            "worksiteId": "110:203793983",
            "changeType": "unchanged",
            "changedFields": [],
            "addedAndRemovedEmployments": []
        },
        {
            "worksiteId": "110:203793982",
            "changeType": "updated",
            "changedFields": [
                {
                    "jsonPath": "$.postalAddress",
                    "lastModifiedAt": "2015-03-23T11:02:32.527Z"
                },
                {
                    "jsonPath": "$.name",
                    "lastModifiedAt": "2014-10-10T00:11:28.672Z"
                }
            ],
            "addedAndRemovedEmployments": [
                {
                    "type": "addition",
                    "employmentId": "110:412443401",
                    "at": "2015-03-23T11:02:32.561Z"
                },
                {
                    "type": "removal",
                    "employmentId": "110:405360287",
                    "at": "2015-03-23T11:02:32.575Z"
                }
            ]
        }
    ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Worksite changes response",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "changes": {
      "type": "array",
      "items": {
        "title": "Worksite Change Entry",
        "type": "object",
        "properties": {
          "worksiteId": {
            "description": "A worksite ID (provided by Bisnode)",
            "type": "string"
          },
          "changeType": {
            "description": "The type of change.",
            "enum": [
              "unchanged",
              "updated",
              "removed"
            ]
          },
          "changedFields": {
            "description": "A list of all changed fields",
            "type": "array",
            "items": {
              "title": "Changed field",
              "type": "object",
              "properties": {
                "jsonPath": {
                  "description": "The JSON path in the worksite document for the affected field",
                  "type": "string"
                },
                "lastModifiedAt": {
                  "description": "The date and time when this field was last changed (ISO-8601 extended offset date-time format, 2015-03-10T13:02:51.692+01:00)",
                  "type": "string"
                }
              },
              "required": [
                "jsonPath",
                "lastModifiedAt"
              ],
              "additionalProperties": false
            }
          },
          "addedAndRemovedEmployments": {
            "type": "array",
            "items": {
              "title": "Added or removed employments",
              "type": "object",
              "properties": {
                "type": {
                  "description": "Type of change",
                  "enum": [
                    "addition",
                    "removal"
                  ]
                },
                "employmentId": {
                  "description": "A employment ID (provided by Bisnode)",
                  "type": "string"
                },
                "at": {
                  "description": "Date and time when this employment has been added or removed",
                  "type": "string"
                }
              },
              "required": [
                "type",
                "employmentId",
                "at"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "worksiteId",
          "changeType",
          "changedFields",
          "addedAndRemovedEmployments"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "$schema",
    "changes"
  ]
}

Employments

Search, download and query changes for employments

/employments get

get

Search/filter by provided parameters

Request
Response

Query Parameters

maxSize: (integer - default: 10 - maximum: 10000)
Max number of results to provide in each resultset
Example:
```
20
```
offset: (integer - maximum: 10000)
The current offset in the total result set hit count (totalHits in the search result data)
Example:
```
10
```
fulltext: (string)
Search within all fields at once, for example company name and city (see example below)
Example:
```
Bisnode Stockholm
```
country: (string - pattern: ^[A-Za-z]{2}$)
ISO country code.
Available country codes may be retrieved through the /countries endpoint.
Example:
```
DE
```
generalName: (string)
Search by the name of the associated worksite or company
companyLegalName: (string)
Search by the legal name of the associated company
worksiteGeneralAddress: (string)
Search by postal address and visiting address
worksiteGeneralCity: (string)
Search by worksite city location
worksiteGeneralZipcode: (string)
Search by worksite zip code
phone: (string)
Search by associated worksite phone numbers
Example:
```
004412345678
```
worksiteType: (string)
Search by type of worksite
Example:
```
TY10
```
worksiteStatus: (string)
Search by status of the worksite
Example:
```
ST00
```
contactFirstName: (string)
Search employees by first name
contactLastName: (string)
Search employees by last name
contactName: (string)
Search in both the contactFirstName and contactLastName fields
email: (string)
Search employees by e-mail address
worksiteNumber: (string)
Search by worksite number
companyNumber: (string)
Search by company registration number or company VAT number

HTTP status code 200

A employment-search resource

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/employment-search.schema.json",
    "employments": [{
        "firstName": "Mats",
        "lastName": "Lönnqvist",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU2310001",
            "description": "Financial Manager"
        },
        "worksite": {
            "id": "1:200099336",
            "name": "Bisnode AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/001200099336"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/001100277670"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/001403733092"
            }
        },
        "id": "1:403733092"
    }, {
        "firstName": "Jon",
        "lastName": "Risfelt",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU1110001",
            "description": "Member of Board"
        },
        "worksite": {
            "id": "1:200099336",
            "name": "Bisnode AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/001200099336"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/001100277670"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/001403762469"
            }
        },
        "id": "1:403762469"
    }, {
        "firstName": "Meri",
        "lastName": "Kavak",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU2540001",
            "description": "Other Decision Maker"
        },
        "worksite": {
            "id": "1:200099336",
            "name": "Bisnode AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200099336"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100277670"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/1:403755052"
            }
        },
        "id": "1:403755052"
    }, {
        "firstName": "Carina",
        "lastName": "Erlandsson",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU2540001",
            "description": "Other Decision Maker"
        },
        "worksite": {
            "id": "1:200099336",
            "name": "Bisnode AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/001200099336"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/001100277670"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/001403755051"
            }
        },
        "id": "1:403755051"
    }, {
        "firstName": "Anders",
        "lastName": "Berg",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU1220001",
            "description": "CEO (Managing Director, General Manager, Owner)"
        },
        "worksite": {
            "id": "1:200099336",
            "name": "Bisnode AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200099336"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100277670"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/1:403875284"
            }
        },
        "id": "1:403875284"
    }, {
        "firstName": "Maria",
        "lastName": "Madison",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU2540001",
            "description": "Other Decision Maker"
        },
        "worksite": {
            "id": "1:200099336",
            "name": "Bisnode AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200099336"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100277670"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/1:403755000"
            }
        },
        "id": "1:403755000"
    }, {
        "firstName": "Malin",
        "lastName": "Silander",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU2540001",
            "description": "Other Decision Maker"
        },
        "worksite": {
            "id": "1:200099336",
            "name": "Bisnode AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200099336"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100277670"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/1:403660311"
            }
        },
        "id": "1:403660311"
    }, {
        "firstName": "Zlatko",
        "lastName": "Ninic",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU3121001",
            "description": "IT Manager"
        },
        "worksite": {
            "id": "1:200099336",
            "name": "Bisnode AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200099336"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100277670"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/1:403622102"
            }
        },
        "id": "1:403622102"
    }, {
        "firstName": "Johan",
        "lastName": "Haglund",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU4230001",
            "description": "Product Manager"
        },
        "worksite": {
            "id": "1:200980659",
            "name": "Bisnode Sverige AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200980659"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100846353"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/1:403756359"
            }
        },
        "id": "1:403756359"
    }, {
        "firstName": "Alfred",
        "lastName": "Andersson",
        "status": {
            "name": "Active",
            "code": "ST00"
        },
        "mainPosition": {
            "code": "HU2540001",
            "description": "Other Decision Maker"
        },
        "worksite": {
            "id": "1:200980659",
            "name": "Bisnode Sverige AB",
            "country": "SE",
            "visitingAddress": {
                "address": "Rosenborgsgatan 4",
                "city": "SOLNA"
            },
            "postalAddress": {
                "city": "SOLNA"
            },
            "type": {
                "code": "TY10",
                "description": "Head Office"
            }
        },
        "_links": {
            "worksite": {
                "href": "https://bbc.bisnode.com/v2/worksites/1:200980659"
            },
            "company": {
                "href": "https://bbc.bisnode.com/v2/companies/1:100846353"
            },
            "employment": {
                "href": "https://bbc.bisnode.com/v2/employments/1:403756289"
            }
        },
        "id": "1:403756289"
    }],
    "maxSize": 10,
    "offset": 0,
    "hitsReturned": 10,
    "hitsTotal": 191,
    "_links": {
        "self": {
            "href": "https://bbc.bisnode.com/v2/employments?generalName=Bisnode&worksiteStatus=00&country=SE"
        },
        "first": {
            "href": "https://bbc.bisnode.com/v2/employments?country=SE&generalName=Bisnode&worksiteStatus=00"
        },
        "last": {
            "href": "https://bbc.bisnode.com/v2/employments?country=SE&generalName=Bisnode&worksiteStatus=00&offset=190"
        },
        "next": {
            "href": "https://bbc.bisnode.com/v2/employments?country=SE&generalName=Bisnode&worksiteStatus=00&offset=10"
        }
    }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Employment search result",
  "type": "object",
  "description": "Employment search result schema from the Bisnode Business Contacts API",
  "definitions": {
    "employment": {
      "type": "object",
      "description": "Employment search result item",
      "properties": {
        "firstName": {
          "type": "string",
          "description": "First name of person having the employment"
        },
        "lastName": {
          "type": "string",
          "description": "Last name of person having the employment"
        },
        "id": {
          "type": "string",
          "description": "Id of this employment"
        },
        "mainPosition": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "description": "Position represented as a code"
            },
            "description": {
              "type": "string",
              "description": "Descriptive text of this position"
            }
          }
        },
        "status": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "description": "The employment status represented as code"
            },
            "name": {
              "type": "string",
              "description": "The employment status as text"
            }
          }
        },
        "worksite": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Id of worksite where this employment is located"
            },
            "name": {
              "type": "string",
              "description": "The name of the worksite where this employment is located"
            },
            "country": {
              "type": "string",
              "description": "The ISO country code of this worksites country"
            },
            "visitingAddress": {
              "type": "object",
              "properties": {
                "address": {
                  "type": "string",
                  "description": "Street address"
                },
                "city": {
                  "type": "string",
                  "description": "City"
                }
              }
            },
            "postalAddress": {
              "type": "object",
              "properties": {
                "city": {
                  "type": "string",
                  "description": "City"
                }
              }
            },
            "type": {
              "type": "object",
              "description": "The type of worksite (code and name)",
              "properties": {
                "code": {
                  "type": "string",
                  "description": "The type of worksite represented as a code"
                },
                "description": {
                  "type": "string",
                  "description": "The name or description of the worksite type"
                }
              },
              "additionalProperties": false,
              "required": ["code", "description"]
            }
          },
          "required": ["id", "name", "country"],
          "additionalProperties": false
        },
        "_links": {
          "type": "object",
          "properties": {
            "employment": {
              "type": "object",
              "description": "URL for downloading this search hit",
              "properties": {
                "href": {
                  "type": "string"
                }
              }
            },
            "worksite": {
              "type": "object",
              "description": "URL for downloading the worksite of this search hit",
              "properties": {
                "href": {
                  "type": "string"
                }
              }
            },
            "company": {
              "type": "object",
              "description": "URL for downloading the company of this search hit",
              "properties": {
                "href": {
                  "type": "string"
                }
              }
            }
          },
          "required": ["employment", "worksite", "company"],
          "additionalProperties": false
        }
      },
      "required": ["firstName", "lastName", "id", "worksite", "_links"],
      "additionalProperties": false
    }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "hitsReturned": {
      "type": "integer",
      "description": "The number of hits returned in this resultset"
    },
    "hitsTotal": {
      "type": "integer",
      "description": "The total number of hits for the search"
    },
    "maxSize": {
      "type": "integer",
      "description": "The max number of hits to provide in the search result"
    },
    "offset": {
      "type": "integer",
      "description": "The current offset in the total resultset (if larger than maxSize)"
    },
    "employments": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/employment"
      }
    },
    "_links": {
      "type": "object",
      "description": "Links for navigating the search result. Links of type 'first' and 'last' will always be present while 'previous' and 'next' only will be available when applicable.",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL of the current search result"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the previous search result page (if avaialable)"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the next search result page (if avaialable)"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "first": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the first search result page"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "last": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The pagination URL of the last search result page"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        }
      },
      "additionalProperties": false,
      "required": ["first", "last", "self"]
    }
  },
  "required": ["$schema", "hitsReturned", "hitsTotal", "maxSize", "offset", "_links"],
  "additionalProperties": false
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

/employments/{employmentId} get head

Employment resource entity

get

Get a employment resource

head

See description of GET request for this endpoint

Get a employment resource

Request
Response

URI Parameters

Employment ID: required (string - minLength: 12 - maxLength: 12 - pattern: ^\d{12}$)
Example:
```
1:400537329
```

Query Parameters

language: (string - default: en - minLength: 2 - maxLength: 2 - pattern: ^[a-z]{2}$)
Example:
```
sv
```

HTTP status code 200

A employment resource

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/employment.schema.json",
    "$lastModified": "2015-01-01T00:05:00.000Z",
    "status": {
        "name": "Active",
        "code": "ST00"
    },
    "person": {
        "personId": "1:300033712",
        "firstNames": "Tommy",
        "lastNames": "Berglund",
        "personStatus": {
            "name": "Active",
            "code": "ST00"
        },
        "gender": {
            "name": "Male",
            "code": "SX10"
        },
        "mainCommunicationLanguage": {
            "name": "Swedish",
            "code": "SV"
        }
    },
    "positions": {
        "mainPosition": {
            "code": "HU2180001",
            "description": "Project Manager"
        },
        "subPositions": [
            {
                "code": "BE2540001",
                "description": "Other Decision Maker"
            }
        ],
        "local": {
            "mainPosition": {
                "code": "HU11100",
                "description": "Project Manager"
            },
            "subPositions": [
                {
                    "code": "BE12510",
                    "description": "Other Decision Maker"
                }
            ]
        }
    },
    "internet": {
        "emails": [
            {
                "address": "tommy.berglund@bisnode.com",
                "blocked": false
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://bbc.bisnode.com/v2/employments/1:400033712"
        },
        "company": {
            "href": "https://bbc.bisnode.com/v2/companies/1:100193203"
        },
        "worksite": {
            "href": "https://bbc.bisnode.com/v2/worksites/1:200001039"
        }
    },
    "id": "1:400033712",
    "addressSource": "PARAD, 169 93 Solna, Sweden"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Employment",
  "type": "object",
  "description": "An employment entity from the Bisnode Business Contacts API",
  "definitions": {
    "country": {
      "type": "object",
      "description": "Container of country code and name",
      "properties": {
          "name": {
              "type": "string",
              "description": "The country name in English"
          },
          "code": {
              "type": "string",
              "description": "The ISO country code",
              "maxLength": 2
          }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "status": {
      "type": "object",
      "description": "Container of status by name and code",
      "properties": {
        "name": {
          "type": "string",
          "description": "The status in English"
        },
        "code": {
          "type": "string",
          "description": "The status code"
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "person": {
      "type": "object",
      "description": "The person connected to this employment",
      "properties": {
        "personId": {
          "type": "string",
          "description": "String identifying the person holding this employment. Can be used to identify if a person has multiple employments."
        },
        "personStatus": {
          "$ref": "#/definitions/status"
        },
        "firstNames": {
          "type": "string",
          "description": "The first names of this person"
        },
        "lastNames": {
          "type": "string",
          "description": "The last names of this person"
        },
        "gender": {
          "type": "object",
          "description": "Container of gender name and code",
          "properties": {
            "name": {
              "type": "string",
              "description": "The gender name in english"
            },
            "code": {
              "type": "string",
              "description": "The gender code"
            }
          }
        },
        "mainCommunicationLanguage": {
          "type": "object",
          "description": "The (possibly) preferred language for this person",
          "properties": {
            "name": {
              "type": "string",
              "description": "The language name"
            },
            "code": {
              "type": "string",
              "description": "The language code (EN, DE, SV, etc)",
              "maxLength": 2
            }
          }
        }
      },
      "additionalProperties": false
    },
    "position": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "The code for this position"
        },
        "description": {
          "type": "string",
          "description": "Description of this position"
        }
      },
      "additionalProperties": false
    },
    "positions": {
      "type": "object",
      "description": "Positions related to this employment",
      "properties": {
        "mainPosition": {
          "$ref": "#/definitions/position"
        },
        "subPositions": {
          "type": "array",
          "items": [{
            "$ref": "#/definitions/position"
          }]
        },
        "local": {
          "$ref": "#/definitions/localPositions"
        }
      },
      "additionalProperties": false
    },
    "localPositions": {
      "type": "object",
      "description": "The original local position codes (only available in Sweden)",
      "properties": {
          "mainPosition": {
              "$ref": "#/definitions/position"
          },
          "subPositions": {
              "type": "array",
              "items": [{
                  "$ref": "#/definitions/position"
              }]
          }

      },
      "additionalProperties": false
    },
    "internet": {
      "type": "object",
      "properties": {
        "emails": {
          "type": "array",
          "description": "List of e-mail addresses related to this employment (only available in Sweden and UK)",
          "items": [{
            "type": "object",
            "description": "Contact e-mail address",
            "properties": {
              "address": {
                "type": "string",
                "description": "The e-mail address"
              },
              "blocked": {
                "type": "boolean",
                "description": "Whether this e-mail address is blocked for direct marketing (only available in Sweden)"
              }
            },
            "additionalProperties": false
          }]
        }
      },
      "additionalProperties": false
    },
    "country": {
      "type": "object",
      "description": "Container of country code and name",
      "properties": {
        "name": {
          "type": "string",
          "description": "The country name in english"
        },
        "code": {
          "type": "string",
          "description": "The ISO country code",
          "maxLength": 2
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "county": {
      "type": "object",
      "description": "Container of county code and name",
      "properties": {
        "name": {
          "type": "string",
          "description": "The county name in english"
        },
        "code": {
          "type": "string",
          "description": "The county code (geographic region code)"
        }
      },
      "required": ["name", "code"],
      "additionalProperties": false
    },
    "address": {
      "type": "object",
      "properties": {
        "villageAddress": {
          "type": "string",
          "description": "Address Line 2 of this worksite address"
        },
        "address": {
          "type": "string",
          "description": "Address Line 3 of this worksite address"
        },
        "co": {
          "type": "string",
          "description": "Address Line 1 of this worksite address"
        },
        "zipcode": {
          "type": "string",
          "description": "The zip code of this address"
        },
        "city": {
          "type": "string",
          "description": "The city of this address"
        },
        "country": {
          "$ref": "#/definitions/country"
        },
        "county": {
          "$ref": "#/definitions/county"
        }
      },
      "required": ["zipcode", "city", "country"],
      "additionalProperties": false
    },
    "links": {
      "type": "object",
      "description": "Links to other entities related to this employment",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL reference to this entity"
            }
          },
          "additionalProperties": false
        },
        "company": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL reference to this employment's related company"
            }
          },
          "additionalProperties": false
        },
        "worksite": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL reference to this employment's related worksite"
            }
          },
          "additionalProperties": false
        }
      },
      "required": ["self"],
      "additionalProperties": false
    }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "$lastModified": {
      "type": "string",
      "description": "Date and time when this resource was last updated. Use this string for queries to /worksites/changes."
    },
    "id": {
      "type": "string",
      "description": "The unique identifier of this employment entity",
      "pattern": "\\d{1,3}:\\d{9}"
    },
    "country": {
      "$ref": "#/definitions/country"
    },
    "status": {
      "$ref": "#/definitions/status"
    },
    "person": {
      "$ref": "#/definitions/person"
    },
    "positions": {
      "$ref": "#/definitions/positions"
    },
    "internet": {
      "$ref": "#/definitions/internet"
    },
    "address": {
      "$ref": "#/definitions/address"
    },
    "addressSource": {
      "type": "string",
      "description": "Source of the address information"
    },
    "_links": {
      "$ref": "#/definitions/links"
    }
  },
  "required": ["$schema", "$lastModified", "id"],
  "additionalProperties": false
}

HTTP status code 403

X-Quota-Limit: The yearly quota.
X-Quota-Remaining: Remaining part of the yearly quota.

Headers

X-Quota-Limit: (integer)
X-Quota-Remaining: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Quota limit of 150000 unique entities exceeded. You can still retrieve any entity that you have previously retrieved during the quota period as only unique entities count towards the quota."
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

See description of GET request for this endpoint

Request
Response

URI Parameters

Employment ID: required (string - minLength: 12 - maxLength: 12 - pattern: ^\d{12}$)
Example:
```
1:400537329
```

HTTP status code 200

Same as GET but with empty response body

HTTP status code 403

X-Quota-Limit: The yearly quota.
X-Quota-Remaining: Remaining part of the yearly quota.

Headers

X-Quota-Limit: (integer)
X-Quota-Remaining: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Quota limit of 150000 unique entities exceeded. You can still retrieve any entity that you have previously retrieved during the quota period as only unique entities count towards the quota."
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

/employments/changes post

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.

Request
Response

Body

Type: application/json

Example:

[
  {
    "employmentId": "110:403793981",
    "since": "2014-01-01T00:00:00.000Z"
  },
  {
    "employmentId": "110:403793982",
    "since": "2013-01-01T00:00:00.000Z"
  },
  {
    "employmentId": "110:403793983",
    "since": "2015-01-01T00:00:00.000Z"
  }
]

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Employment changes request",
  "type": "array",
  "items": [
    {
      "type": "object",
      "properties": {
        "employmentId": {
          "description": "A emloyment ID (provided by Bisnode)",
          "type": "string"
        },
        "since": {
          "description": "DateTime saying from how far back you want changes. (ISO-8601 extended offset date-time format, 2015-03-10T13:02:51.692+01:00)",
          "type": "string"
        }
      },
      "required": [
        "employmentId",
        "since"
      ],
      "additionalProperties": false
    }
  ]
}

HTTP status code 200

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/employment-changes-response.schema.json",
    "changes": [
        {
            "employmentId": "110:403793981",
            "changeType": "unchanged",
            "changedFields": []
        },
        {
            "employmentId": "110:403793983",
            "changeType": "unchanged",
            "changedFields": []
        },
        {
            "employmentId": "110:403793982",
            "changeType": "updated",
            "changedFields": [
                {
                    "jsonPath": "$.positions.mainPosition",
                    "lastModifiedAt": "2015-03-23T11:02:32.527Z"
                },
                {
                    "jsonPath": "$.person.firstNames",
                    "lastModifiedAt": "2014-10-10T00:11:28.672Z"
                }
            ]
        }
    ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Employment changes response",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "changes": {
      "type": "array",
      "items": {
        "title": "Employment Change Entry",
        "type": "object",
        "properties": {
          "employmentId": {
            "description": "A employment ID (provided by Bisnode)",
            "type": "string"
          },
          "changeType": {
            "description": "The type of change.",
            "enum": [
              "unchanged",
              "updated",
              "removed"
            ]
          },
          "changedFields": {
            "description": "A list of all changed fields",
            "type": "array",
            "items": {
              "title": "Changed field",
              "type": "object",
              "properties": {
                "jsonPath": {
                  "description": "The JSON path in the company document for the affected field",
                  "type": "string"
                },
                "lastModifiedAt": {
                  "description": "The date and time when this field was last changed (ISO-8601 extended offset date-time format, 2015-03-10T13:02:51.692+01:00)",
                  "type": "string"
                }
              },
              "required": [
                "jsonPath",
                "lastModifiedAt"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "employmentId",
          "changeType",
          "changedFields"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "$schema",
    "changes"
  ]
}

Countries

List all countries covered by this API

/countries get head

get

List all countries covered by this API

head

See description of GET request for this endpoint

List all countries covered by this API

Request
Response

Query Parameters

language: (string - default: en - minLength: 2 - maxLength: 2 - pattern: ^[a-z]{2}$)
Example:
```
sv
```

HTTP status code 200

A countries resource

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/countries.schema.json",
    "countries": [
        {
            "code": "ALL",
            "name": "All countries"
        },
        {
            "code": "AT",
            "name": "Austria"
        },
        {
            "code": "BE",
            "name": "Belgium"
        },
        {
            "code": "CZ",
            "name": "Czech Republic"
        },
        {
            "code": "DK",
            "name": "Denmark"
        },
        {
            "code": "EE",
            "name": "Estonia"
        },
        {
            "code": "FI",
            "name": "Finland"
        },
        {
            "code": "FR",
            "name": "France"
        },
        {
            "code": "DE",
            "name": "Germany"
        },
        {
            "code": "GR",
            "name": "Greece"
        },
        {
            "code": "IT",
            "name": "Italy"
        },
        {
            "code": "LV",
            "name": "Latvia"
        },
        {
            "code": "LT",
            "name": "Lithuania"
        },
        {
            "code": "NL",
            "name": "Netherlands"
        },
        {
            "code": "NO",
            "name": "Norway"
        },
        {
            "code": "PL",
            "name": "Poland"
        },
        {
            "code": "RU",
            "name": "Russia"
        },
        {
            "code": "SK",
            "name": "Slovakia"
        },
        {
            "code": "ES",
            "name": "Spain"
        },
        {
            "code": "SE",
            "name": "Sweden"
        },
        {
            "code": "CH",
            "name": "Switzerland"
        },
        {
            "code": "GB",
            "name": "United Kingdom"
        }
    ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Countries",
  "type": "object",
  "description": "A listing of available countries for the BBC API",
  "definitions": {
    "countries": {
      "type": "array",
      "items": [{
        "type": "object",
        "description": "A country by code and name",
        "properties": {
          "code": {
            "type": "string",
            "description": "The ISO country code for this country"
          },
          "name": {
            "type": "string",
            "description": "The name of this country"
          }
        },
        "additionalProperties": false
      }]
    }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "countries": {
      "$ref": "#/definitions/countries"
    }
  },
  "required": [
    "$schema",
    "countries"
  ],
  "additionalProperties": false
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

See description of GET request for this endpoint

Response

HTTP status code 200

Same as GET but with empty response body

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

Company selection

Returns count of hits within selection

/select/companies get

get

Request
Response

Query Parameters

status: (string)
Shows the status of the company. If its actively run (ST00) or if its discontinued (ST10). Use /codetypes/ST to get all possible codes.
Example:
```
ST00
```
type: (string)
Company type. Private (TY50), Public (TY60) or Unknown TY99. NOTE! TY prefix is also used for worksite type. Use only the codes TY50, TY60, TY99 here.
Example:
```
TY50
```
county: (string)
County is a code that represents a geographical area within a country. These codes have different meaning in each contry and must therefore be prefixed with a country code. SE:GR01 for Sweden:Stockholm and LV:GR01 for Latvia:Riga. Use /codetypes/GR to get all possible codes.
Example:
```
SE:GR01
```
municipality: (string)
Municipality is a code that represents an area and division government within a country. These codes have different meaning in each country and must therefore be prefixed with a country code. SE:GK2281 for Sweden:Sundsvall and DE:GK06412 for Germany:Frankfurt. We only have this data in Norway, Sweden, Finland, Denmark, Germany, Polen, Czech Republic and Slovenia. Use /codetypes/GK to get all possible codes.
Example:
```
SE:GK2281
```
mainActivity: (string)
HG is a NACE code. XM is a local that must be prefixed with a country code. Example of local code is SE:XM41100. Where SE is the country code XM is to show its a local code and 41100 is from the SNI (Swedish Standard Industrial Classification).
Example:
```
SE:XM41100, HG18
```
numberOfEmployees: (string)
Number of employees is a code prefixed with AA. AA04 means that its a company with 10 to 19 employees. Use /codetypes/AA to get all possible codes.
Example:
```
AA04
```
numberOfOfficeEmployees: (string)
Sum of all office employees in the company's worksites. Code prefixed with KA. KA04 means that its a company with 20 to 49 office employees. Use /codetypes/KA to get all possible codes.
Example:
```
KA05
```
turnover: (string)
Turnover is a code representing the turnover of a company. OM06 is code for a turnover between 10,000,000 and 25,000,000 EUR (10000 - 25000 Kilo EUR). Use /codetypes/OM to get all possible codes.
Example:
```
OM06
```
hasPhone: (string)
If included in the query string then only companies where we have a phone number are included. You should not send any value here. Just use it in the query string without any value "?hasPhone"
hasEmail: (string)
If included in the query string then only companies where we have an email address are included. You should not send any value here. Just use it in the query string without any value "?hasEmail"
city: (string)
City in a given country. Will only include perfect matches. So if we enter SE:Stockholm we get all the companies in Stockholm sweden. But SE:Stockhol gives us an empty result.
Example:
```
SE:Stockholm
```
zipcode: (string)
The local postal code in a given country. The given values must be prefixed with a country code. SE:17550. It also accepts ranges such as SE:[17550,17560]
Example:
```
SE:17550
```
creationDate: (string)
Creation date of the company. You should give a date range which the company must be within to be included in the result. The range can be open on either side. [2011-12-24,] or [,2011-12-24]
Example:
```
[2011-12-24,2012-02-15]
```
country: (string)
The country the company is in. You should give a two character country code is found in "ISO 3166-1 alpha-2".
Example:
```
DE
```
legalForm: (string)
Legel form is a local term that must be prefixed with a country code. Use /codetypes/JF to get all possible codes.
Example:
```
SE:JF00
```

HTTP status code 200

Returns size of the result. Use the /extract/companies path to get the ids.

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/select.schema.json",
    "size": 18449069,
    "_links": {
        "self": {
            "href": "https://bbc.bisnode.com/v2/select/companies?hasPhone="
        },
        "ids": {
            "href": "https://bbc.bisnode.com/v2/extract/companies?hasPhone="
        }
    }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Select result",
  "type": "object",
  "description": "Select result schema from the Bisnode Business Contacts API",
  "definitions": {
      "preview": {
          "type": "object",
          "description": "A preview of the result entity",
          "properties": {
              "companyName": {
                  "type": "string",
                  "description": "The legal name of the company"
              },
              "country": {
                  "type": "string",
                  "description": "The ISO country code of this entity's country"
              },
              "id": {
                  "type": "string",
                  "description": "ID of the entity"
              },
              "city": {
                  "type": "string",
                  "description": "Postal address for company and worksite visit address for worksite and employments"
              },
              "size": {
                  "type": "object",
                  "description": "Number of employees on the company (code and name) or on worksite for worksite and employments",
                  "properties": {
                      "code": {
                          "type": "string",
                          "description": "Number of employees represented as a code"
                      },
                      "name": {
                          "type": "string",
                          "description": "Number of employees code description"
                      }
                  },
                  "additionalProperties": false,
                  "required": ["code", "name"]
              },
              "status": {
                  "type": "object",
                  "description": "The status of the entity (code and name)",
                  "properties": {
                      "code": {
                          "type": "string",
                          "description": "The status of the entity represented as a code"
                      },
                      "name": {
                          "type": "string",
                          "description": "The name or description of the entity status"
                      }
                  },
                  "additionalProperties": false,
                  "required": ["code", "name"]
              },
              "mainPosition": {
                  "type": "object",
                  "properties": {
                      "code": {
                          "type": "string",
                          "description": "Position represented as a code"
                      },
                      "description": {
                          "type": "string",
                          "description": "Descriptive text of this position"
                      }
                  }
              }
          },
          "required": ["id", "companyName", "country", "status"],
          "additionalProperties": false
      }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "size": {
      "type": "integer",
      "description": "Size of selection. This is the number of entities that matches the given selection criteria."
    },
      "previews": {
          "type": "array",
          "description": "A list of selection preview results",
          "items": {
              "$ref": "#/definitions/preview"
          }
      },
    "_links": {
      "type": "object",
      "description": "Links for navigating the selection result.",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL of the current selection result"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "ids": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL for retrieving a list of ids representing this selection. The the content type for this URL is text/plain."
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        }
      },
      "additionalProperties": false,
      "required": ["self", "ids"]
    }
  },
  "required": ["$schema", "size", "_links"],
  "additionalProperties": false
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

Extract company selection

Returns all the company IDs within selection.

/extract/companies get

get

Request
Response

Query Parameters

status: (string)
Shows the status of the company. If its actively run (ST00) or if its discontinued (ST10). Use /codetypes/ST to get all possible codes.
Example:
```
ST00
```
type: (string)
Company type. Private (TY50), Public (TY60) or Unknown TY99. NOTE! TY prefix is also used for worksite type. Use only the codes TY50, TY60, TY99 here.
Example:
```
TY50
```
county: (string)
County is a code that represent a geographical area within a country. These codes have different meaning in each contry and must therefore be prefixed with a country code. SE:GR01 for Sweden:Stockholm and LV:GR01 for Latvia:Riga. Use /codetypes/GR to get all possible codes.
Example:
```
SE:GR01
```
municipality: (string)
Municipality is a code that represents an area and division government within a country. These codes have different meaning in each country and must therefore be prefixed with a country code. SE:GK2281 for Sweden:Sundsvall and DE:GK06412 for Germany:Frankfurt. We only have this data in Norway, Sweden, Finland, Denmark, Germany, Polen, Czech Republic and Slovenia. Use /codetypes/GK to get all possible codes.
Example:
```
SE:GK2281
```
mainActivity: (string)
HG is a NACE code. XM is a local that must be prefixed with a country code. Example of local code is SE:XM41100. Where SE is the country code XM is to show its a local code and 41100 is from the SNI (Swedish Standard Industrial Classification).
Example:
```
SE:XM41100, HG18
```
numberOfEmployees: (string)
Number of employees is a code prefixed with AA. AA04 means that its a company with 10 to 19 employees. Use /codetypes/AA to get all possible codes.
Example:
```
AA04
```
numberOfOfficeEmployees: (string)
Sum of all office employees in the company's worksites. Code prefixed with KA. KA04 means that its a company with 20 to 49 office employees. Use /codetypes/KA to get all possible codes.
Example:
```
KA05
```
turnover: (string)
Turnover is a code representing the turnover of a company. OM06 is code for a turnover between 10,000,000 and 25,000,000 EUR (10000 - 25000 Kilo EUR). Use /codetypes/OM to get all possible codes.
Example:
```
OM06
```
hasPhone: (string)
If included in the query string then only companies where we have a phone number are included. You should not send any value here. Just use it in the query string without any value "?hasPhone"
hasEmail: (string)
If included in the query string then only companies where we have an email address are included. You should not send any value here. Just use it in the query string without any value "?hasEmail"
city: (string)
City in a given country. Will only include perfect matches. So if we enter SE:Stockholm we get all the companies in Stockholm sweden. But SE:Stockhol gives us an empty result.
Example:
```
SE:Stockholm
```
zipcode: (string)
The local postal code in a given country. The given values must be prefixed with a country code. SE:17550. It also accepts ranges such as SE:[17550,17560]
Example:
```
SE:17550
```
creationDate: (string)
Creation date of the company. You should give a date range which the company must be within to be included in the result. The range can be open on either side. [2011-12-24,] or [,2011-12-24]
Example:
```
[2011-12-24,2012-02-15]
```
country: (string)
The country the company is in. You should give a two character country code is found in "ISO 3166-1 alpha-2".
Example:
```
DE
```
legalForm: (string)
Legel form is a local term that must be prefixed with a country code. Use /codetypes/JF to get all possible codes.
Example:
```
SE:JF00
```

HTTP status code 200

Returns all the company ID within selection

Body

Type: text/plain

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

1:101128971
1:100184005
1:100233114
1:100698870
1:100007151
1:102972513
1:100299537
1:100292900
1:100377838
1:100230566
1:100237707
1:100324634
1:100205432
1:101236506
1:100287448
1:100218703
1:103257349
1:102894220
1:100238773
1:101984718
1:100334175
1:101426158
1:100309653

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

Worksite match

Initiate matching.

/match/worksites post

post

Request
Response

Body

Type: application/json

Example:

{
    "meta": {
        "historicalData": true,
        "matchingMatrix": "ECP Standard",
        "multipleHits": false
    },
    "records": [
        {
            "referenceId": "1w837492qa",
            "companyNames": ["Eastman Kodak Company", "Kodak"],
            "countryCode": "SE",
            "nationalIds": ["5563057743", "SE556305774301"],
            "addresses": [
                {
                    "type": "visiting",
                    "addressLine1": "Rosenborgsgatan 4-6",
                    "postalCode": "16974",
                    "postalTown": "Solna"
                },
                {
                    "type": "postal",
                    "addressLine1": "Box 1234",
                    "addressLine2": "Hus 3",
                    "postalCode": "16993",
                    "postalTown": "Solna"
                }
            ],
            "phoneNumbers": ["08-55805900","020-343410","08-55805595"],
            "webAddress": "www.bisnode.com",
            "email": "info@bisnode.com",
            "contactPersons": [
                {
                    "firstName": "Lars-Inge",
                    "lastName": "Pettersson"
                }
            ]
        }
    ]
}

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Worksite match init",
    "type": "object",
    "description": "Worksite match init schema from the Bisnode Business Contacts API",
    "definitions": {
        "address": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "enum": ["visiting", "postal"],
                    "description": ""
                },
                "addressLine1": {
                    "type": "string",
                    "description": ""
                },
                "addressLine2": {
                    "type": "string",
                    "description": ""
                },
                "addressLine3": {
                    "type": "string",
                    "description": ""
                },
                "postalCode": {
                    "type": "string",
                    "description": ""
                },
                "postalTown": {
                    "type": "string",
                    "description": ""
                }
            },
            "additionalProperties": false
        },
        "contactPerson": {
            "type": "object",
            "properties": {
                "firstName": {
                    "type": "string",
                    "description": ""
                },
                "lastName": {
                    "type": "string",
                    "description": ""
                }
            },
            "additionalProperties": false
        },
        "record": {
            "type": "object",
            "properties": {
                "referenceId": {
                    "type": "string",
                    "description": "Your ID on the record."
                },
                "companyNames": {
                    "type": "array",
                    "description": "Array of strings. No more than 4. First string should preferably be registered name. Additional strings are for secondary names or trade style.",
                    "minItems": 1,
                    "maxItems": 4,
                    "items": {
                        "type": "string"
                    }
                },
                "countryCode": {
                    "type": "string",
                    "description": "ISO 3166-1 alpha-2"
                },
                "nationalIds": {
                    "type": "array",
                    "description": "Array of strings. No more than 4. National registration number, VAT number etc.",
                    "maxItems": 4,
                    "items": {
                        "type": "string"
                    }
                },
                "addresses": {
                    "type": "array",
                    "description": "Array of addresses. No more than 2.",
                    "maxItems": 2,
                    "items": {
                        "$ref": "#/definitions/address"
                    }
                },
                "phoneNumbers": {
                    "type": "array",
                    "description": "Array of strings. No more than 4. Preferably worksite numbers. Landlines, mobile phones, fax numbers.",
                    "maxItems": 4,
                    "items": {
                        "type": "string"
                    }
                },
                "webAddress": {
                    "type": "string",
                    "description": "Aaddress to company website"
                },
                "email": {
                    "type": "string",
                    "description": "Company email address"
                },
                "contactPersons": {
                    "type": "array",
                    "description": "Array of contactPersons. No more than 2.",
                    "maxItems": 2,
                    "items": {
                        "$ref": "#/definitions/contactPerson"
                    }
                }
            },
            "required": ["referenceId", "companyNames", "countryCode"],
            "additionalProperties": false
        }
    },
    "properties": {
        "meta": {
            "type": "object",
            "description": "Object for matching configuration",
            "properties": {
                "historicalData": {
                    "type": "boolean",
                    "description": "",
                    "default": false
                },
                "matchingMatrix": {
                    "type": "string",
                    "description": "",
                    "enum": ["ECP 04", "ECP Standard", "ECP Total"],
                    "default": "ECP Standard"
                },
                "multipleHits": {
                    "type": "boolean",
                    "description": "",
                    "default": false
                }
            },
            "additionalProperties": false
        },
        "records": {
            "type": "array",
            "description": "Array of objects (records) to be matched. A maximum of 5000 records are accepted.",
            "maxItems": 5000,
            "items": {
                "$ref": "#/definitions/record"
            }
        },
        "additionalProperties": false
    },
    "required": ["records"],
    "additionalProperties": false
}

HTTP status code 202

Request accepted and queued for processing.

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "ticketId": "59c38ebe051d2f00d1a61b4",
    "recordCount": 20,
    "receivedAt": "2017-10-20T13:20:27.168"
}

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Worksite match init result",
    "type": "object",
    "description": "Worksite match init result schema from the Bisnode Business Contacts API",
    "properties": {
        "ticketId": {
            "type": "string",
            "description": "Ticket ID of the initiated match"
        },
        "recordCount": {
            "type": "integer",
            "description": ""
        },
        "receivedAt": {
            "type": "string",
            "description": ""
        }
    },
    "required": ["ticketId", "recordCount", "receivedAt"],
    "additionalProperties": false
}

HTTP status code 413

Error when supplying more than 5000 entries.

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "status": "PAYLOAD_TOO_LARGE",
    "timestamp": "2017-10-20T13:20:27.168",
    "message": "Too many records in the request. Up to 5000 records per request is allowed."
}

/match/worksites/{ticketId} get

Fetch matching.

get

Request
Response

URI Parameters

ticketId: required (string)

HTTP status code 200

The matching status and result.

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "id": "59ba4d62b1541e00cdd36b8e",
    "status": "COMPLETED",
    "receivedAt": "2017-09-14T11:35:30.088+02:00",
    "finishedAt": "2017-09-14T12:38:06.307+02:00",
    "matchResults": [
        {
            "referenceId": "218701",
            "matchStatus": "SINGLE_HIT",
            "matchCandidates": [
                {
                    "worksiteId": "1:200000428",
                    "worksiteStatus": {
                        "code": "A",
                        "description": "Active"
                    },
                    "companyId": "1:100518667",
                    "confidenceCode": "10",
                    "dataSource": "ECP"
                }
            ]
        },
        {
            "referenceId": "218702",
            "matchStatus": "MULTIPLE_HITS",
            "matchCandidates": [
                {
                    "worksiteId": "1:200000428",
                    "worksiteName": "Eli Engine",
                    "worksiteType": "Head office",
                    "worksitePhoneNumber": "+46 8500271",
                    "worksiteEmployees": "0",
                    "worksiteStatus": {
                        "code": "A",
                        "description": "Active"
                    },
                    "worksiteAddresses": [
                        {
                            "type": "postal",
                            "addressLine1": "c/o Silverhammar",
                            "addressLine2": null,
                            "addressLine3": "Spikbergsvägen 1",
                            "postalCode": "11796",
                            "postalTown": "HUSMORA"
                        }
                    ],
                    "companyId": "1:100518667",
                    "companyNationalId": "5590339114",
                    "companyVatNumber": "559033911401",
                    "companyName": "Eli Engine AB",
                    "confidenceCode": "10",
                    "dataSource": "ECP"
                }
            ]
        },
        {
            "referenceId": "218703",
            "matchStatus": "NO_HITS",
            "matchCandidates": []
        }
    ]
}

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Worksite match result",
    "type": "object",
    "description": "Worksite match result schema from the Bisnode Business Contacts API",
    "definitions": {
        "worksiteAddress": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "enum": ["visiting", "postal"],
                    "description": ""
                },
                "addressLine1": {
                    "type": "string",
                    "description": ""
                },
                "addressLine2": {
                    "type": "string",
                    "description": ""
                },
                "addressLine3": {
                    "type": "string",
                    "description": ""
                },
                "postalCode": {
                    "type": "string",
                    "description": ""
                },
                "postalTown": {
                    "type": "string",
                    "description": ""
                }
            },
            "additionalProperties": false
        },
        "matchCandidate": {
            "type": "object",
            "properties": {
                "worksiteId": {
                    "type": "string",
                    "description": "Our entity ID. Used to get full data and monitoring."
                },
                "worksiteName": {
                    "type": "string",
                    "description": "Name of worksite. Might be trade name. Returned for MULTIPLE_HITS only."
                },
                "worksiteType": {
                    "type": "string",
                    "enum": ["Head office", "Branch office"],
                    "description": "Possible values are \"Head office\" or \"Branch office\". Returned for MULTIPLE_HITS only."
                },
                "worksitePhoneNumber": {
                    "type": "string",
                    "description": "Phone number to worksite. Returned for MULTIPLE_HITS only."
                },
                "worksiteEmployees": {
                    "type": "string",
                    "description": "Number of employees at worksite. Returned for MULTIPLE_HITS only."
                },
                "worksiteStatus": {
                    "type": "object",
                    "description": "The worksites status. An object with two properties",
                    "properties": {
                        "code": {
                            "type": "string",
                            "enum": ["A", "B", "N"],
                            "description": "A: Active. B: Blocked for direct marketing. N: Inactive"
                        },
                        "description": {
                            "type": "string",
                            "description": "Code description."
                        }
                    },
                    "additionalProperties": false
                },
                "worksiteAddresses": {
                    "type": "array",
                    "description": "Array of up to two addresses to the worksite. Returned for MULTIPLE_HITS only.",
                    "items": {
                        "$ref": "#/definitions/worksiteAddress"
                    }
                },
                "companyId": {
                    "type": "string",
                    "description": "Our entity ID for the company."
                },
                "companyNationalId": {
                    "type": "string",
                    "description": "National ID for the company. Returned for MULTIPLE_HITS only."
                },
                "companyVatNumber": {
                    "type": "string",
                    "description": "VAT Number for the company. Returned for MULTIPLE_HITS only."
                },
                "confidenceCode": {
                    "type": "string",
                    "description": "Match score. Possible value is blank, 0-14."
                },
                "dataSource": {
                    "type": "string",
                    "enum": ["ECP", "ECP Historic"],
                    "description": "Possible values are \"ECP\" and \"ECP Historic\"."
                }
            },
            "additionalProperties": false
        },
        "matchResult": {
            "type": "object",
            "description": "",
            "properties": {
                "referenceId": {
                    "type": "string",
                    "description": "Your ID, returned from the request."
                },
                "matchStatus": {
                    "type": "string",
                    "enum": ["SINGLE_HIT", "MULTIPLE_HITS", "NO_HIT"],
                    "description": "SINGLE_HIT: returned for single hits according to chosen match matrix. MULTIPLE_HITS: returned for multiple hits above match matrix threshold and when confidence code is below matrix threshold, down to 0. NO_HITS: Returned for remaining confidence codes or null."
                },
                "matchCandidates": {
                    "type": "array",
                    "description": "Array of match candidates. Returned when matchStatus is SINGLE_HIT or MULTIPLE_HITS only. One object is returned for SINGLE_HIT. Three objects are returned for MULTIPLE_HITS but do not rely on that specific number as it might change.",
                    "items": {
                        "$ref": "#/definitions/matchCandidate"
                    }
                }
            },
            "additionalProperties": false
        }
    },
    "properties": {
        "id": {
            "type": "string",
            "description": "the ticket id"
        },
        "status": {
            "type": "string",
            "enum": ["IN_PROGRESS", "COMPLETED", "ERROR", "TIMED_OUT", "EXPIRED"],
            "description": "IN_PROGRESS, when matching is processing. COMPLETED, when matching is done. ERROR, when input can’t be validated or matching couldn’t be performed. TIMED_OUT, when no matching result has been returned within 2 hours. EXPIRED, when matching result can no longer be retrieved"
        },
        "receivedAt": {
            "type": "string",
            "description": "When the match job was received in the API"
        },
        "finishedAt": {
            "type": "string",
            "description": "When the match job was completed"
        },
        "matchResults": {
            "type": "arrays",
            "description": "Array of match results. Returned only when status is COMPLETED",
            "items": {
                "$ref": "#/definitions/matchResult"
            }
        }
    },
    "required": ["id", "status", "receivedAt"],
    "additionalProperties": false
}

HTTP status code 404

Match not found.

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "status": "NOT_FOUND",
    "timestamp": "2017-10-20T13:20:27.168",
    "message": "Match with id 59c38ebe051d2f00d1a61b4 was not found"
}

Worksite selection

Returns count of hits within selection

/select/worksites get

get

Request
Response

Query Parameters

status: (string)
Shows the status of the worksite. If its actively run (ST00) or if its discontinued (ST10). Use /codetypes/ST to get all possible codes.
Example:
```
ST00
```
type: (string)
Worksite type. Main office (TY10), branch (TY20) or Unknown TY99. NOTE! TY prefix is also used for company type. Use only the codes TY10, TY20, TY99 here.
Example:
```
TY20
```
county: (string)
County is a code that represent a geographical area within a country. These codes have different meaning in each contry and must therefore be prefixed with a country code. SE:GR01 for Sweden:Stockholm and LV:GR01 for Latvia:Riga. Use /codetypes/GR to get all possible codes.
Example:
```
SE:GR01
```
municipality: (string)
Municipality is a code that represents an area and division government within a country. These codes have different meaning in each country and must therefore be prefixed with a country code. SE:GK2281 for Sweden:Sundsvall and DE:GK06412 for Germany:Frankfurt. We only have this data in Norway, Sweden, Finland, Denmark, Germany, Polen, Czech Republic and Slovenia. Use /codetypes/GK to get all possible codes.
Example:
```
SE:GK2281
```
mainActivity: (string)
HG is a NACE code. XM is a local that must be prefixed with a country code. Example of local code is SE:XM41100. Where SE is the country code XM is to show its a local code and 41100 is from the SNI (Swedish Standard Industrial Classification).
Example:
```
SE:XM41100, HG18
```
employmentMainPosition: (string)
Can be prefixed with a country code. Must be prefixed with HU,XB,
numberOfEmployees: (string)
Number of employees is a code prefixed with AA. AA04 means that its a worksite with 10 to 19 employees. Use /codetypes/AA to get all possible codes.
Example:
```
AA04
```
numberOfOfficeEmployees: (string)
Number of office employees is a code prefixed with KA. KA04 means that its a worksite with 20 to 49 employees. Use /codetypes/KA to get all possible codes.
Example:
```
KA05
```
companyTurnover: (string)
Turnover is a code representing the turnover of a company. OM06 is code for a turnover between 10,000,000 and 25,000,000 EUR (10000 - 25000 Kilo EUR). Use /codetypes/OM to get all possible codes.
Example:
```
OM06
```
hasPhone: (string)
If included in the query string then only worksites where we have a phone number are included. You should not send any value here. Just use it in the query string without any value "?hasPhone"
hasEmail: (string)
If included in the query string then only worksites where we have an email address are included. You should not send any value here. Just use it in the query string without any value "?hasEmail"
city: (string)
City in a given country. Will only include perfect matches. So if we enter SE:Stockholm we get all the worksites in Stockholm sweden. But SE:Stockhol gives us an empty result.
Example:
```
SE:Stockholm
```
zipcode: (string)
The local postal code in a given country. The given values must be prefixed with a country code. SE:17550. It also accepts ranges such as SE:[17550,17560]
Example:
```
SE:17550
```
companyCreationDate: (string)
Creation date of the company. You should give a date range which the company must be within to be included in the result. The range can be open on either side. [2011-12-24,] or [,2011-12-24]
Example:
```
[2011-12-24,2012-02-15]
```
country: (string)
The country the worksite is in. You should give a two character country code found in "ISO 3166-1 alpha-2".
Example:
```
DE
```
companyLegalForm: (string)
Legel form is a local term that must be prefixed with a country code. Use /codetypes/JF to get all possible codes.
Example:
```
SE:JF00
```

HTTP status code 200

Returns size of the result. Use the /extract/worksites path to get the ids.

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/select.schema.json",
    "size": 12449069,
    "_links": {
        "self": {
            "href": "https://bbc.bisnode.com/v2/select/worksites?hasPhone="
        },
        "ids": {
            "href": "https://bbc.bisnode.com/v2/extract/worksites?hasPhone="
        }
    }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Select result",
  "type": "object",
  "description": "Select result schema from the Bisnode Business Contacts API",
  "definitions": {
      "preview": {
          "type": "object",
          "description": "A preview of the result entity",
          "properties": {
              "companyName": {
                  "type": "string",
                  "description": "The legal name of the company"
              },
              "country": {
                  "type": "string",
                  "description": "The ISO country code of this entity's country"
              },
              "id": {
                  "type": "string",
                  "description": "ID of the entity"
              },
              "city": {
                  "type": "string",
                  "description": "Postal address for company and worksite visit address for worksite and employments"
              },
              "size": {
                  "type": "object",
                  "description": "Number of employees on the company (code and name) or on worksite for worksite and employments",
                  "properties": {
                      "code": {
                          "type": "string",
                          "description": "Number of employees represented as a code"
                      },
                      "name": {
                          "type": "string",
                          "description": "Number of employees code description"
                      }
                  },
                  "additionalProperties": false,
                  "required": ["code", "name"]
              },
              "status": {
                  "type": "object",
                  "description": "The status of the entity (code and name)",
                  "properties": {
                      "code": {
                          "type": "string",
                          "description": "The status of the entity represented as a code"
                      },
                      "name": {
                          "type": "string",
                          "description": "The name or description of the entity status"
                      }
                  },
                  "additionalProperties": false,
                  "required": ["code", "name"]
              },
              "mainPosition": {
                  "type": "object",
                  "properties": {
                      "code": {
                          "type": "string",
                          "description": "Position represented as a code"
                      },
                      "description": {
                          "type": "string",
                          "description": "Descriptive text of this position"
                      }
                  }
              }
          },
          "required": ["id", "companyName", "country", "status"],
          "additionalProperties": false
      }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "size": {
      "type": "integer",
      "description": "Size of selection. This is the number of entities that matches the given selection criteria."
    },
      "previews": {
          "type": "array",
          "description": "A list of selection preview results",
          "items": {
              "$ref": "#/definitions/preview"
          }
      },
    "_links": {
      "type": "object",
      "description": "Links for navigating the selection result.",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL of the current selection result"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "ids": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL for retrieving a list of ids representing this selection. The the content type for this URL is text/plain."
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        }
      },
      "additionalProperties": false,
      "required": ["self", "ids"]
    }
  },
  "required": ["$schema", "size", "_links"],
  "additionalProperties": false
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

Extract worksites selection

Returns all the worksite IDs within selection.

/extract/worksites get

get

Request
Response

Query Parameters

status: (string)
Shows the status of the worksite. If its actively run (ST00) or if its discontinued (ST10). Use /codetypes/ST to get all possible codes.
Example:
```
ST00
```
type: (string)
Worksite type. Main office (TY10), branch (TY20) or Unknown TY99. NOTE! TY prefix is also used for company type. Use only the codes TY10, TY20, TY99 here.
Example:
```
TY20
```
county: (string)
County is a code that represent a geographical area within a country. These codes have different meaning in each contry and must therefore be prefixed with a country code. SE:GR01 for Sweden:Stockholm and LV:GR01 for Latvia:Riga. Use /codetypes/GR to get all possible codes.
Example:
```
SE:GR01
```
municipality: (string)
Municipality is a code that represents an area and division government within a country. These codes have different meaning in each country and must therefore be prefixed with a country code. SE:GK2281 for Sweden:Sundsvall and DE:GK06412 for Germany:Frankfurt. We only have this data in Norway, Sweden, Finland, Denmark, Germany, Polen, Czech Republic and Slovenia. Use /codetypes/GK to get all possible codes.
Example:
```
SE:GK2281
```
mainActivity: (string)
HG is a NACE code. XM is a local that must be prefixed with a country code. Example of local code is SE:XM41100. Where SE is the country code XM is to show its a local code and 41100 is from the SNI (Swedish Standard Industrial Classification).
Example:
```
SE:XM41100, HG18
```
employmentMainPosition: (string)
Can be prefixed with a country code. Must be prefixed with HU,XB,
numberOfEmployees: (string)
Number of employees is a code prefixed with AA. AA04 means that its a worksite with 10 to 19 employees. Use /codetypes/AA to get all possible codes.
Example:
```
AA04
```
numberOfOfficeEmployees: (string)
Number of office employees is a code prefixed with KA. KA04 means that its a worksite with 20 to 49 employees. Use /codetypes/KA to get all possible codes.
Example:
```
KA05
```
companyTurnover: (string)
Turnover is a code representing the turnover of a company. OM06 is code for a turnover between 10,000,000 and 25,000,000 EUR (10000 - 25000 Kilo EUR). Use /codetypes/OM to get all possible codes.
Example:
```
OM06
```
hasPhone: (string)
If included in the query string then only worksites where we have a phone number are included. You should not send any value here. Just use it in the query string without any value "?hasPhone"
hasEmail: (string)
If included in the query string then only worksites where we have an email address are included. You should not send any value here. Just use it in the query string without any value "?hasEmail"
city: (string)
City in a given country. Will only include perfect matches. So if we enter SE:Stockholm we get all the worksites in Stockholm sweden. But SE:Stockhol gives us an empty result.
Example:
```
SE:Stockholm
```
zipcode: (string)
The local postal code in a given country. The given values must be prefixed with a country code. SE:17550. It also accepts ranges such as SE:[17550,17560]
Example:
```
SE:17550
```
companyCreationDate: (string)
Creation date of the company. You should give a date range which the company must be within to be included in the result. The range can be open on either side. [2011-12-24,] or [,2011-12-24]
Example:
```
[2011-12-24,2012-02-15]
```
country: (string)
The country the worksite is in. You should give a two character country code found in "ISO 3166-1 alpha-2".
Example:
```
DE
```
companyLegalForm: (string)
Legel form is a local term that must be prefixed with a country code. Use /codetypes/JF to get all possible codes.
Example:
```
SE:JF00
```

HTTP status code 200

Returns all the worksite IDs within selection

Body

Type: text/plain

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

1:200054688
1:200172174
1:201777210
1:200234260
1:200121063
1:200964077
1:200054818
1:201749937
1:200223082
1:200692246
1:200794248
1:202212742
1:201409321
1:202290804

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

Employments selection

Returns count of hits within selection

/select/employments get

get

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

Request
Response

Query Parameters

mainPosition: (string)
Main position. Must be prefixed with HU (global) or XB (local).
Example:
```
HU1220001
```
hasEmail: (string)
If included in the query string then only employments where we have an email address are included. You should not send any value here. Just use it in the query string without any value "?hasEmail"
country: (string)
The country the employment is in. You should give a two character country code found in "ISO 3166-1 alpha-2".
Example:
```
DE
```
gender: (string)
Gender of the employee. male (SX10), female (SX20) or unknown (SX99).
Example:
```
SX20
```
worksiteStatus: (string)
Shows the status of the worksite. If its actively run (ST00) or if its discontinued (ST10). Use /codetypes/ST to get all possible codes.
Example:
```
ST00
```
worksiteType: (string)
Worksite type. Main office (TY10), branch (TY20) or Unknown TY99. NOTE! TY prefix is also used for company type. Use only the codes TY10, TY20, TY99 here.
Example:
```
TY20
```
worksiteCounty: (string)
County is a code that represent a geographical area within a country. These codes have different meaning in each contry and must therefore be prefixed with a country code. SE:GR01 for Sweden:Stockholm and LV:GR01 for Latvia:Riga. Use /codetypes/GR to get all possible codes.
Example:
```
SE:GR01
```
worksiteMunicipality: (string)
Municipality is a code that represents an area and division government within a country. These codes have different meaning in each country and must therefore be prefixed with a country code. SE:GK2281 for Sweden:Sundsvall and DE:GK06412 for Germany:Frankfurt. We only have this data in Norway, Sweden, Finland, Denmark, Germany, Polen, Czech Republic and Slovenia. Use /codetypes/GK to get all possible codes.
Example:
```
SE:GK2281
```
worksiteMainActivity: (string)
HG is a NACE code. XM is a local that must be prefixed with a country code. Example of local code is SE:XM41100. Where SE is the country code XM is to show its a local code and 41100 is from the SNI (Swedish Standard Industrial Classification).
Example:
```
SE:XM41100, HG18
```
worksiteNumberOfEmployees: (string)
Number of employees is a code prefixed with AA. AA04 means that its a worksite with 10 to 19 employees. Use /codetypes/AA to get all possible codes.
Example:
```
AA04
```
hasWorksitePhone: (string)
If included in the query string then only employees with worksites where we have a phone number are included. You should not send any value here. Just use it in the query string without any value "?hasPhone"
worksiteCity: (string)
City in a given country. Will only include perfect matches. So if we enter SE:Stockholm we get all the employees with worksites in Stockholm sweden. But SE:Stockhol gives us an empty result.
Example:
```
SE:Stockholm
```
worksiteZipcode: (string)
The local postal code in a given country. The given values must be prefixed with a country code. SE:17550. It also accepts ranges such as SE:[17550,17560]
Example:
```
SE:17550
```
companyNumberOfEmployees: (string)
Number of employees is a code prefixed with AA. AA04 means that its a company with 10 to 19 employees. Use /codetypes/AA to get all possible codes.
Example:
```
AA04
```
companyTurnover: (string)
Turnover is a code representing the turnover of a company. OM06 is code for a turnover between 10,000,000 and 25,000,000 EUR (10000 - 25000 Kilo EUR). Use /codetypes/OM to get all possible codes.
Example:
```
OM06
```
companyCreationDate: (string)
Creation date of the company. You should give a date range which the company must be within to be included in the result. The range can be open on either side. [2011-12-24,] or [,2011-12-24]
Example:
```
[2011-12-24,2012-02-15]
```
companyLegalForm: (string)
Legel form is a local term that must be prefixed with a country code. Use /codetypes/JF to get all possible codes.
Example:
```
SE:JF00
```

HTTP status code 200

Returns size of the result. Use the /extract/employments path to get the ids.

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "$schema": "https://bbc.bisnode.com/v2/schemas/select.schema.json",
    "size": 18449,
    "_links": {
        "self": {
            "href": "https://bbc.bisnode.com/v2/select/employments?hasEmail="
        },
        "ids": {
            "href": "https://bbc.bisnode.com/v2/extract/employments?hasEmail="
        }
    }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Select result",
  "type": "object",
  "description": "Select result schema from the Bisnode Business Contacts API",
  "definitions": {
      "preview": {
          "type": "object",
          "description": "A preview of the result entity",
          "properties": {
              "companyName": {
                  "type": "string",
                  "description": "The legal name of the company"
              },
              "country": {
                  "type": "string",
                  "description": "The ISO country code of this entity's country"
              },
              "id": {
                  "type": "string",
                  "description": "ID of the entity"
              },
              "city": {
                  "type": "string",
                  "description": "Postal address for company and worksite visit address for worksite and employments"
              },
              "size": {
                  "type": "object",
                  "description": "Number of employees on the company (code and name) or on worksite for worksite and employments",
                  "properties": {
                      "code": {
                          "type": "string",
                          "description": "Number of employees represented as a code"
                      },
                      "name": {
                          "type": "string",
                          "description": "Number of employees code description"
                      }
                  },
                  "additionalProperties": false,
                  "required": ["code", "name"]
              },
              "status": {
                  "type": "object",
                  "description": "The status of the entity (code and name)",
                  "properties": {
                      "code": {
                          "type": "string",
                          "description": "The status of the entity represented as a code"
                      },
                      "name": {
                          "type": "string",
                          "description": "The name or description of the entity status"
                      }
                  },
                  "additionalProperties": false,
                  "required": ["code", "name"]
              },
              "mainPosition": {
                  "type": "object",
                  "properties": {
                      "code": {
                          "type": "string",
                          "description": "Position represented as a code"
                      },
                      "description": {
                          "type": "string",
                          "description": "Descriptive text of this position"
                      }
                  }
              }
          },
          "required": ["id", "companyName", "country", "status"],
          "additionalProperties": false
      }
  },
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The URL of the JSON Schema that this document conforms to."
    },
    "size": {
      "type": "integer",
      "description": "Size of selection. This is the number of entities that matches the given selection criteria."
    },
      "previews": {
          "type": "array",
          "description": "A list of selection preview results",
          "items": {
              "$ref": "#/definitions/preview"
          }
      },
    "_links": {
      "type": "object",
      "description": "Links for navigating the selection result.",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL of the current selection result"
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        },
        "ids": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "The URL for retrieving a list of ids representing this selection. The the content type for this URL is text/plain."
            }
          },
          "additionalProperties": false,
          "required": ["href"]
        }
      },
      "additionalProperties": false,
      "required": ["self", "ids"]
    }
  },
  "required": ["$schema", "size", "_links"],
  "additionalProperties": false
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

Extract employments selection

Returns all the employment ID within selection

/extract/employments get

get

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

Request
Response

Query Parameters

mainPosition: (string)
Main position. Must be prefixed with HU (global) or XB (local).
Example:
```
HU1220001
```
hasEmail: (string)
If included in the query string then only employments where we have an email address are included. You should not send any value here. Just use it in the query string without any value "?hasEmail"
country: (string)
The country the employment is in. You should give a two character country code found in "ISO 3166-1 alpha-2".
Example:
```
DE
```
gender: (string)
Gender of the employee. male (SX10), female (SX20) or unknown (SX99).
Example:
```
SX20
```
worksiteStatus: (string)
Shows the status of the worksite. If its actively run (ST00) or if its discontinued (ST10). Use /codetypes/ST to get all possible codes.
Example:
```
ST00
```
worksiteType: (string)
Worksite type. Main office (TY10), branch (TY20) or Unknown TY99. NOTE! TY prefix is also used for company type. Use only the codes TY10, TY20, TY99 here.
Example:
```
TY20
```
worksiteCounty: (string)
County is a code that represent a geographical area within a country. These codes have different meaning in each contry and must therefore be prefixed with a country code. SE:GR01 for Sweden:Stockholm and LV:GR01 for Latvia:Riga. Use /codetypes/GR to get all possible codes.
Example:
```
SE:GR01
```
worksiteMunicipality: (string)
Municipality is a code that represents an area and division government within a country. These codes have different meaning in each country and must therefore be prefixed with a country code. SE:GK2281 for Sweden:Sundsvall and DE:GK06412 for Germany:Frankfurt. We only have this data in Norway, Sweden, Finland, Denmark, Germany, Poland, Czech Republic and Slovenia. Use /codetypes/GK to get all possible codes.
Example:
```
SE:GK2281
```
worksiteMainActivity: (string)
HG is a NACE code. XM is a local that must be prefixed with a country code. Example of local code is SE:XM41100. Where SE is the country code XM is to show its a local code and 41100 is from the SNI (Swedish Standard Industrial Classification).
Example:
```
SE:XM41100, HG18
```
worksiteNumberOfEmployees: (string)
Number of employees is a code prefixed with AA. AA04 means that its a worksite with 10 to 19 employees. Use /codetypes/AA to get all possible codes.
Example:
```
AA04
```
hasWorksitePhone: (string)
If included in the query string then only employees with worksites where we have a phone number are included. You should not send any value here. Just use it in the query string without any value "?hasPhone"
worksiteCity: (string)
City in a given country. Will only include perfect matches. So if we enter SE:Stockholm we get all the employees with worksites in Stockholm sweden. But SE:Stockhol gives us an empty result.
Example:
```
SE:Stockholm
```
worksiteZipcode: (string)
The local postal code in a given country. The given values must be prefixed with a country code. SE:17550. It also accepts ranges such as SE:[17550,17560]
Example:
```
SE:17550
```
companyNumberOfEmployees: (string)
Number of employees is a code prefixed with AA. AA04 means that its a company with 10 to 19 employees. Use /codetypes/AA to get all possible codes.
Example:
```
AA04
```
companyTurnover: (string)
Turnover is a code representing the turnover of a company. OM06 is code for a turnover between 10,000,000 and 25,000,000 EUR (10000 - 25000 Kilo EUR). Use /codetypes/OM to get all possible codes.
Example:
```
OM06
```
companyCreationDate: (string)
Creation date of the company. You should give a date range which the company must be within to be included in the result. The range can be open on either side. [2011-12-24,] or [,2011-12-24]
Example:
```
[2011-12-24,2012-02-15]
```
companyLegalForm: (string)
Legel form is a local term that must be prefixed with a country code. Use /codetypes/JF to get all possible codes.
Example:
```
SE:JF00
```

HTTP status code 200

Returns all the employment ID within selection

Body

Type: text/plain

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

1:404275402
1:401377880
1:403670880
1:404341198
1:402456756
1:404352357
1:402695963
1:402695958
1:402122970
1:402695966
1:403289003
1:400535575
1:402796672
1:402309019
1:403055147
1:402695960
1:402695965
1:403726946
1:401468793
1:402695964
1:403233488
1:404352358
1:404448695
1:403810251
1:403027193
1:401215294
1:404341199

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

Codetypes

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

/codetypes get

get

Response

HTTP status code 200

Returns size of the result. Use the /extract/employments path to get the ids.

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
    "codetypes": [
        {
            "unknownCode": "AA99",
            "codetype": "AA",
            "name": "Size",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/AA"
                }
            }
        },
        {
            "unknownCode": "AK99",
            "codetype": "AK",
            "name": "Share capital",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/AK"
                }
            }
        },
        {
            "unknownCode": "BE2540001",
            "codetype": "BE",
            "name": "Position",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/BE"
                }
            }
        },
        {
            "unknownCode": "CO",
            "codetype": "CO",
            "name": "Country",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/CO"
                }
            }
        },
        {
            "unknownCode": "CT",
            "codetype": "CT",
            "name": "City type",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/CT"
                }
            }
        },
        {
            "unknownCode": "EQ99",
            "codetype": "EQ",
            "name": "Total equity",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/EQ"
                }
            }
        },
        {
            "unknownCode": "GA",
            "codetype": "GA",
            "name": "Workforce region",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/GA"
                }
            }
        },
        {
            "unknownCode": "GB",
            "codetype": "GB",
            "name": "Block region",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/GB"
                }
            }
        },
        {
            "unknownCode": "GK",
            "codetype": "GK",
            "name": "Municipality",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/GK"
                }
            }
        },
        {
            "unknownCode": "GP",
            "codetype": "GP",
            "name": "Municipality Group",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/GP"
                }
            }
        },
        {
            "unknownCode": "GR",
            "codetype": "GR",
            "name": "Region",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/GR"
                }
            }
        },
        {
            "unknownCode": "HG0000900",
            "codetype": "HG",
            "name": "Main line of business",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/HG"
                }
            }
        },
        {
            "unknownCode": "HU2540001",
            "codetype": "HU",
            "name": "",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/HU"
                }
            }
        },
        {
            "unknownCode": "JF99",
            "codetype": "JF",
            "name": "Legal form",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/JF"
                }
            }
        },
        {
            "unknownCode": "KA99",
            "codetype": "KA",
            "name": "Office size",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/KA"
                }
            }
        },
        {
            "unknownCode": "LA99",
            "codetype": "LA",
            "name": "Language",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/LA"
                }
            }
        },
        {
            "unknownCode": "NC",
            "codetype": "NC",
            "name": "Line of business",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/NC"
                }
            }
        },
        {
            "unknownCode": "NO99",
            "codetype": "NO",
            "name": "Turnover change",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/NO"
                }
            }
        },
        {
            "unknownCode": "NS99",
            "codetype": "NS",
            "name": "Solidity",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/NS"
                }
            }
        },
        {
            "unknownCode": "OF",
            "codetype": "OF",
            "name": "Public sector code",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/OF"
                }
            }
        },
        {
            "unknownCode": "OM99",
            "codetype": "OM",
            "name": "Turnover",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/OM"
                }
            }
        },
        {
            "unknownCode": "OV",
            "codetype": "OV",
            "name": "Other code",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/OV"
                }
            }
        },
        {
            "unknownCode": "PO",
            "codetype": "PO",
            "name": "",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/PO"
                }
            }
        },
        {
            "unknownCode": "SN",
            "codetype": "SN",
            "name": "Local line of business",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/SN"
                }
            }
        },
        {
            "unknownCode": "ST99",
            "codetype": "ST",
            "name": "Status",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/ST"
                }
            }
        },
        {
            "unknownCode": "SX99",
            "codetype": "SX",
            "name": "",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/SX"
                }
            }
        },
        {
            "unknownCode": "TY99",
            "codetype": "TY",
            "name": "Entity type",
            "$schema": "https://bbc.bisnode.com/v2/schemas/global-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/TY"
                }
            }
        },
        {
            "unknownCode": "XA",
            "codetype": "XA",
            "name": "Local line of business",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/XA"
                }
            }
        },
        {
            "unknownCode": "XB",
            "codetype": "XB",
            "name": "Local position",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/XB"
                }
            }
        },
        {
            "unknownCode": "XK99",
            "codetype": "XK",
            "name": "Local office size",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/XK"
                }
            }
        },
        {
            "unknownCode": "XM0000900",
            "codetype": "XM",
            "name": "Local main line of business",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/XM"
                }
            }
        },
        {
            "unknownCode": "XO99",
            "codetype": "XO",
            "name": "Local turnover",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/XO"
                }
            }
        },
        {
            "unknownCode": "XS99",
            "codetype": "XS",
            "name": "Local size",
            "$schema": "https://bbc.bisnode.com/v2/schemas/local-code-type.schema.json",
            "_links": {
                "self": {
                    "href": "https://bbc.bisnode.com/v2/codetypes/XS"
                }
            }
        }
    ],
    "$schema": "https://bbc.bisnode.com/v2/schemas/code-type-list.schema.json",
    "_links": {
        "self": {
            "href": "https://bbc.bisnode.com/v2/codetypes"
        }
    }
}

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Code Type List",
    "type": "object",
    "description": "List of all Code Types schema from the Bisnode Business Contacts API",
    "properties": {
        "$schema": {
            "type": "string",
            "description": "The URL of the JSON Schema that this document conforms to."
        },
        "_links": {
            "type": "object",
            "description": "Links for navigation.",
            "properties": {
                "self": {
                    "type": "object",
                    "properties": {
                        "href": {
                            "type": "string",
                            "description": "The URL of this list"
                        }
                    },
                    "additionalProperties": false,
                    "required": [
                        "href"
                    ]
                }
            },
            "additionalProperties": false,
            "required": [
                "self"
            ]
        },
        "codetypes": {
            "type": "array",
            "items": [
                {
                    "type": "object",
                    "properties": {
                        "$schema": {
                            "type": "string",
                            "description": "The url of the schema for this codetype"
                        },
                        "_links": {
                            "type": "object",
                            "description": "Links for navigation.",
                            "properties": {
                                "self": {
                                    "type": "object",
                                    "properties": {
                                        "href": {
                                            "type": "string",
                                            "description": "The URL of this codetype"
                                        }
                                    },
                                    "additionalProperties": false,
                                    "required": [
                                        "href"
                                    ]
                                }
                            },
                            "additionalProperties": false,
                            "required": [
                                "self"
                            ]
                        },
                        "codetype": {
                            "type": "string",
                            "description": "The codetype"
                        },
                        "name": {
                            "type": "string",
                            "description": "A brief description of this codetype"
                        },
                        "unknownCode": {
                            "type": "string",
                            "description": "The code indicating an unknown value"
                        }
                    },
                    "required": [
                        "$schema",
                        "_links",
                        "codetype",
                        "name",
                        "unknownCode"
                    ]
                }
            ]
        }
    },
    "required": [
        "$schema",
        "codetypes",
        "_links"
    ],
    "additionalProperties": false
}

HTTP status code 429

Usage of this API is rate limited to 50 requests per second.

Headers

Retry-After: (integer)

Body

Type: application/json

Example:

The following example has been constructed to illustrate the kind of data that may be returned. It does not necessarily show a real-world example.

{
  "message": "Rate limit exceeded, try again in 1 second."
}

Bisnode Business Contacts API documentation version v2

Introduction

API Change log

2018-04-09

2018-03-28

2017-04-11

2017-02-02

Entities and endpoints

Companies

Worksites

Employments

Search and download

Keep your data up to date

Selection (Filtering)

Working with VAT numbers and Nordic organization numbers

API access

Step 1. Get the access token

Step 2. Use the access token

Reusing the access token

Backwards compatibility for CRM integrators

Hyperlinks

HAL

Benefits

Search navigation

API Versioning

What constitutes an API version

Providing API version

Resources

Companies

get /companies

Query Parameters

HTTP status code 200

Body

HTTP status code 429

Headers

Body

get /companies/{companyId}

URI Parameters

Query Parameters

HTTP status code 200

Body

HTTP status code 403

Headers

Body

HTTP status code 429

Headers

Body

head /companies/{companyId}

URI Parameters

HTTP status code 200

HTTP status code 403

Headers

Body

HTTP status code 429

Headers

Body

post /companies/changes

Body

HTTP status code 200

Body

Worksites

get /worksites

Query Parameters

HTTP status code 200

Body

HTTP status code 429

Headers

Body

get /worksites/{worksiteId}

URI Parameters

Query Parameters

HTTP status code 200

Body

HTTP status code 403

Headers

Body

HTTP status code 429

Headers

Body

head /worksites/{worksiteId}