Migration Guide: v2.0 to v2.1

This guide covers the changes required to migrate from data access version 2.0 to version 2.1.

Overview

v2.1 simplifies the API by consolidating portfolio_id and sku into a single credential_id. Your credential is pre-configured with the appropriate SKU and bureau settings, reducing the number of parameters needed in requests.

Key Change

Replace portfolio_id + sku with a single credential_id in all requests.

What's Changing

1. Order Requests

Endpoint: POST /v2/data-access/orders (unchanged)

Before (v2.0):

{
  "data": {
    "type": "orders",
    "attributes": {
      "consumer_id": "8932c731-8a5b-40d6-92d5-f338d8e4e5be",
      "portfolio_id": "19b0174f-d831-4bca-a13c-9acf75497a9b",
      "sku": "equifax-bronze-hard"
    }
  }
}

After (v2.1):

{
  "data": {
    "type": "orders",
    "attributes": {
      "consumer_id": "8932c731-8a5b-40d6-92d5-f338d8e4e5be",
      "credential_id": "19b0174f-d831-4bca-a13c-9acf75497a9b"
    }
  }
}

2. Header Route Update

To use V2.1 instead of V2.0, include the X-Bas-Router header in your requests.

Example Request with X-Bas-Router Header

 curl --location --request POST 'https://sandbox.bloom.dev/v2/data-access/orders/' \
 --header 'Authorization: Bearer <ACCESS_TOKEN>' \
 --header 'X-Bas-Router: true' \
 --header 'Content-Type: application/json' \
 --data-raw '{
     "data": {
         "type": "orders",
         "attributes": {
             "consumer_id": "<CONSUMER_ID>",
             "credential_id": "<CREDENTIAL_ID>"
         }
     }
 }'

⚠️
Important
Without the X-Bas-Router: true header, requests will continue routing to v2.0.

3. Order Responses

Endpoint: GET /v2/data-access/orders/{orderId} (unchanged)

Before (v2.0):

{
  "data": {
    "type": "orders",
    "id": "a7b14fc8-d2c2-4297-8e30-96a9947e31db",
    "attributes": {
      "consumer_id": "8932c731-8a5b-40d6-92d5-f338d8e4e5be",
      "portfolio_id": "0da2c731-8a5b-40d6-92d5-f338d8e4e5be",
      "sku": "equifax-bronze-hard",
      "order_placed": "2022-12-19T18:07:10.900Z",
      "status": "SUCCESS",
      "status_code": "30"
    }
  }
}

After (v2.1):

{
  "data": {
    "type": "orders",
    "id": "a7b14fc8-d2c2-4297-8e30-96a9947e31db",
    "attributes": {
      "consumer_id": "8932c731-8a5b-40d6-92d5-f338d8e4e5be",
      "credential_id": "0da2c731-8a5b-40d6-92d5-f338d8e4e5be",
      "order_placed": "2022-12-19T18:07:10.900Z",
      "status": "SUCCESS",
      "status_code": "30"
    }
  }
}

4. Query Parameters

Endpoint: GET /v2/data-access/orders (unchanged)

When listing or filtering orders:

Example:

GET /v2/data-access/orders?credential_id=19b0174f-d831-4bca-a13c-9acf75497a9b&status=SUCCESS

5. Subscriptions (Batch Ordering)

Endpoint: POST /v2/data-access/subscriptions (unchanged)

Before (v2.0):

{
  "data": {
    "type": "subscriptions",
    "attributes": {
      "organization_id": "539008ae-e1ff-42ed-8a58-e3588befea9d",
      "sku": "equifax-bronze-batch-account-review",
      "output_credentials": "s3://bucket/path",
      "frequency": "WEEKLY"
    }
  }
}

After (v2.1):

{
  "data": {
    "type": "subscriptions",
    "attributes": {
      "credential_id": "19b0174f-d831-4bca-a13c-9acf75497a9b",
      "output_credentials": "s3://bucket/path",
      "frequency": "WEEKLY"
    }
  }
}

Note

Subscription responses also change from organization_id to credential_id. Also, sku is not included in the response back.

What's NOT Changing

No changes required

• API Endpoints – All URLs remain the same (/v2/data-access/...)
• Authentication – Same OAuth flow using your client ID and secret
• Consumer creation – Same Consumer PII Service endpoints
• Status codes – Same codes and meanings (00, 10, 30, etc.)

Migration Checklist

Before going live

• Obtain your credential_id from Bloom (replaces portfolio_id + sku)
• Update order creation requests to use credential_id
• Update order response parsing to read credential_id instead of portfolio_id
• Update any query filters from portfolio_id to credential_id
• Update subscription requests to use credential_id (if using batch ordering)
• Test in sandbox environment

Getting Your Credential ID

Your credential_id will be provided by Bloom during onboarding or migration. Each credential is tied to:

• Your organization
• A specific SKU (product)
• Bureau credentials (if applicable)

Multiple SKUs

If you have multiple SKUs, you will receive multiple credential IDs. Use the appropriate credential ID for each product type.

Support

For questions or assistance with migration, contact your Bloom representative.