> For the complete documentation index, see [llms.txt](https://developers.bloomcredit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bloomcredit.io/docs/v2.1/quick-start/migration-guide.md).

# Migration Guide

<br>

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

{% hint style="info" %}
**Key Change**

Replace `portfolio_id` + `sku` with a single `credential_id` in all requests.
{% endhint %}

***

### What's Changing

#### 1. Order Requests

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

**Before (v2.0):**

{% code title="JSON" %}

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

{% endcode %}

**After (v2.1):**

{% code title="JSON" %}

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

{% endcode %}

| 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 BAS instead of BOS |

<details>

<summary>Example Request with X-Bas-Router Header</summary>

{% code title="cURL" %}

```bash
 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>"
         }
     }
 }'
```

{% endcode %}

</details>

{% hint style="warning" icon="triangle-exclamation" %}
Important

Without the X-Bas-Router: true header, requests will continue routing to v2.0.
{% endhint %}

***

#### 3. Order Responses

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

**Before (v2.0):**

{% code title="JSON" %}

```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"
    }
  }
}
```

{% endcode %}

**After (v2.1):**

{% code title="JSON" %}

```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"
    }
  }
}
```

{% endcode %}

***

#### 4. Query Parameters

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

When listing or filtering orders:

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

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

{% code title="JSON" %}

```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"
    }
  }
}
```

{% endcode %}

**After (v2.1):**

{% code title="JSON" %}

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

{% endcode %}

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

{% hint style="info" %}
**Note**

Subscription responses also change from `organization_id` to `credential_id`. Also, `sku` is not included in the response back.
{% endhint %}

***

### What's NOT Changing

{% hint style="success" %}
**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.)
  {% endhint %}

***

### Migration Checklist

{% hint style="warning" %}
**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
  {% endhint %}

***

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

{% hint style="warning" %}
**Multiple SKUs**

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

***

### Support

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bloomcredit.io/docs/v2.1/quick-start/migration-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.