# 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):**

```json
{
  "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):**

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

| Removed | Replaced With |
| --- | --- |
| `portfolio_id` | `credential_id` |
| `sku` | (embedded in credential) |

* * *

### 2. Header Route Update

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

| Header | Value | Description |
| --- | --- | --- |
| `X-Bas-Router` | `true` | Routes the request to v2.1 instead of v2.0 |

Example Request with X-Bas-Router Header

```curl
 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):**

```json
{
  "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):**

```json
{
  "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:

| Before | After |
| --- | --- |
| `portfolioId` | `credential_id` |

**Example:**

```undefined
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):**

```json
{
  "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):**

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

| Removed | Replaced With |
| --- | --- |
| `organization_id` | (derived from credential) |
| `sku` | (embedded in credential) |

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