Introduction¶

The Consumer Intelligence API allows you to connect consumers in your systems to real persons in the real world.

Prerequisites¶

API keys required

Before you get started, you need your client_id and client_secret credentials. Apply for access to get them.

Fetching mocked or real persons¶

You have one set of credentials for the sandbox environment and one for the production environment. Before making any requests, decide whether to fetch mocked or real persons.

For mocked persons, use the sandbox environment
For real persons, use the production environment

The rest of this guide refers to the sandbox environment. For real persons, change URLs to the ones of the production environment found here.

Step 1: Get an API access token¶

First, call the D&B OAuth API using client_id and client_secret.

This guide uses cURL for examples, but you can use Postman or any other HTTP client you prefer. We maintain an updated Postman collection you can use to get started.

In the examples below, replace the entire string inside the brackets, including the brackets.

Token request example

curl https://login.bisnode.com/sandbox/v1/token.oauth2 \
    -X POST \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials&scope=bci" \
    -u "{YOUR_CLIENT_ID}:{YOUR_CLIENT_SECRET}"

If you provided the correct values, you should receive a successful response containing an access_token.

Token response example

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

Step 2: Identify a person¶

Next, use your access_token and use the Find API to identify a person.

Access permissions required

Below example requires your client to have Onboarding permissions to the market SE. Check the available persons in Sandbox to find persons in markets you have permissions to. Contact us if you need help.

Identify person request example

curl https://sandbox-api.bisnode.com/consumer-intelligence/v3/markets/SE/persons/_find \
  -X POST \
  -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "legalId": "199412285736"
  }'

Step 3: Upload consumer¶

The available persons changes daily. You can subscribe to changes by using the Consumer upload API with the same data you used to identify the person.

Access permissions required

Below example requires your client to have Monitoring permissions to the market SE. Check the available persons in Sandbox to find persons in markets you have permissions to. Contact us if you need help.

Upload consumer request example

curl https://sandbox-api.bisnode.com/consumer-intelligence/v3/consumers \
  -X POST \
  -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '[
      {
        "consumerId": "{YOUR_CONSUMER_ID}",
        "market": "SE",
        "data": {
          "legalId": "199412285736"
        }
      }
    ]'

Consumer Intelligence will respond with 202 Accepted if the request was successful.

Step 4: Download changes¶

Once your uploaded consumer, it will automatically be identified in your configured sources for the given market. Upon identification, the identified person will be subscribed to any new changes.

You can use the Subscription API to download the latest data of your subscribed persons.

Subscription request example

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

The response will contain a list of subscriptions in ascending order of change.

Subscription response example

{
  "nextPageToken": "{NEXT_PAGE_TOKEN}",
  "data": [
    {
      "gedi": "{GEDI_OF_PERSON}",
      "consumerIds": [
        "{YOUR_CONSUMER_ID}"
      ],
      "person": {
        // data of the person
      }
    }
  ]
}

You must use the nextPageToken to traverse the list subscription until you the data element is empty. Once data is empty, you've reached the end of your changes.

Next subscription request example

curl https://sandbox-api.bisnode.com/consumer-intelligence/v3/subscriptions/persons?pageToken={NEXT_PAGE_TOKEN} \
  -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

Next subscription response example

{
  "nextPageToken": "{NEXT_PAGE_TOKEN}",
  "data": []
}

Persist nextPageToken

Persist the nextPageToken for future jobs to start downloading changes since your last retrieval.

All done!¶

Congratulations on making your first API calls the Consumer Intelligence API! To learn more about using our API, you can: