Consumer Intelligence V3 (1.0.0)

This reference provides a comprehensive overview of the Consumer Intelligence API endpoints for accessing and subscribing to person data and related statistical analytical data.

The API follows REST principles, and uses OAuth 2.0.

ℹ️ Getting started

New to the API? Explore our guides to learn how to make your first API calls.

We provide multiple environments, each with unique data access policies, and live/mocked persons.

Environments are isolated from each other. Client credentials are tied to a specific environment and cannot be reused across environments.

Features the latest stable software, live persons, and strict data access controls.

Includes the latest stable software and mocked persons.

The Consumer Intelligence API uses OAuth 2.0 client access tokens for authenticating server requests.

Consumer Intelligence API access begins with a client and its corresponding client ID and client secret. Clients organize data, are separate, and relate to a specific environment.

API credentials are used to obtain an access token for accessing client-wide endpoints and user-specific endpoints.

⚠️ Keep your API credentials secret

Transmit and store your API credentials securely. Avoid including them in source code. If you suspect a leak, contact customer support.

Generating a new secret immediately invalidates the previous one, blocking access for all API requests using it. Note that this action is irreversible.

⚠️ Getting access to API credentials

Clients are only issued by contacting us.

The access token authorizes client access to all data and functionality. Obtain it via the OAuth 2.0 client credentials grant using the API credentials and the relevant OAuth URLs for your client's environment.

curl https://login.bisnode.com/as/token.oauth2  \
-X POST \
-u {YOUR_CLIENT_ID}:{YOUR_CLIENT_SECRET} \
-d "grant_type=client_credentials&scope=bci"

After requesting the token URL, you'll receive an access token in the response. Cache this token on your server until it expires and needs refreshing. Keep the access token secret.

{
    "access_token": "{YOUR_ACCESS_TOKEN}",
    "expires_in": 3600,
    "scope": "bci",
    "token_type": "bearer"
}

ℹ️ Use an existing OAuth client for authentication

Our API follows the OAuth 2.0 specification without modification, allowing you to use various OAuth clients for authentication. We recommend this over creating your own implementation. See this reference for available clients in your language.

Access tokens expire hourly, indicated by the expires_in key in the response. When expired, obtain a new token.

Authenticate all API requests using a bearer authentication header. This header accesses client-wide endpoints (e.g. persons, consumers, webhooks, etc.).

curl https://api.bisnode.com/consumer-intelligence/v3/webhooks \
-H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \

When using an access_token to access resources, you may encounter the following 4XX range HTTP Status Codes:

In all cases, an RFC7807 Problem Details body is returned to aid in debugging.

Consumer Intelligence endpoints returning collections of a specific type of resource, such as GET /consumers, will return a paginated response. Each response will consist of a subset of the resources, called a page.To retrieve the entire collection, subsequent pages need to be fetched.

Each response includes two properties: data and nextPageToken. The data property contains the records of the current page and the nextPageToken property contains the cursor of the next page. The cursors are unique identifiers for specific records in the dataset that help you keep track of your position and navigate through the pages.

When querying a paginated endpoint, you may provide the following pagination query parameters:

• pageSize
• pageToken

All of these pagination query parameters are optional. If pageSize is not provided, the default page size of 100 is used. If pageToken is not provided, the returned page will contain the first set of resources in the collection.

Responses from most paginated endpoints are sorted in ascending order according to when the resource was created. Hence, for a request like GET /consumers, the most dated uploaded consumers appear on the first page.

The nextPageToken property in a paginated response typically looks like this:

{
  "nextPageToken": "4fsezJ2bJf3Jz3zbfwBuCRWsh"
}

The nextPageToken property provides the cursor required to fetch the next page of resources.

If you are on the last page, there are no more subsequent resources. nextPageToken will then be null. The only endpoint this differs from is the List subscribed person and List audit events endpoints, in which case the cursor is supposed to be used as a way to start retrieving changes that has happened since last.

Consumer Intelligence's API is versioned. A new version is released when breaking changes occur, while new features and bug fixes (additive changes) are available in all API versions.

Some endpoints we have are labelled. Here's an explanation of each label:

Beta

This endpoint is now feature complete and the implementation will not change. There may be bugs or stability issues but they are actively being worked on. We are still open to receiving feedback before delivering a stable release.

Experimental

This endpoint is being released in an early stage to get feedback. There are likely bugs or other issues that may not necessarily be prioritized. The whole implementation may be completely changed or removed.