Connected Solutions Experience API SDK

1. Authentication
1. NodeJS
2. Browser
2. Usage
1. Response format
2. Alerts
3. Credit Reports
4. Credit Attributes
5. Credit Scores
6. Credit Score Planner
7. Credit Score Simulator
8. Customer Auth
9. Customers
10. Entitlements
11. Product Configs
12. Registrations
3. Utilities
1. Type Guards

Authentication

$3

* #### Instantiate the sdk

``tsx
import { createSDK } from '@experian-ecs/connected-api-sdk'

// environment can either be 'PRODUCTION' or 'SANDBOX'
const sdk = createSDK({ environment: 'PRODUCTION' })
`

* #### Retrieve an access token

`tsx
const tokenRequest = await sdk.auth.getAccessToken({
grantType: 'trusted_partner',
clientId: process.env.SDK_CLIENT_ID!,
clientSecret: process.env.SDK_CLIENT_SECRET!,
customerId: 'cus_01'
});
`

* #### Set the authentication token on the sdk instance

`tsx
sdk.setConfig({
token: tokenRequest.data?.access_token
});
`

$3

If using the sdk in the browser the auth.getAccessToken method will throw an error to prevent the user from exposing their client id and client secret in the public browser environment. Because of this, the user will need to retrieve a valid oauth token outside of the sdk and provide it to the configuration object passed to createSDK.

* #### Instantiate the sdk with a token

`tsx
import { createSDK } from '@experian-ecs/connected-api-sdk'

// environment can either be 'PRODUCTION' or 'SANDBOX'
const sdk = createSDK({
environment: 'PRODUCTION',
token: 'your-oauth-token'
})
`

Usage

$3

* All calls to sdk methods return a single object with data, error, meta keys.

`tsx
const { data, error, meta } = await sdk.creditScores.getCreditScores();
`

* Success example

`tsx
{
data: [ {...}, {...} ],
error: undefined,
meta: {
status: 200,
statusText: 'OK'
}
}
`

* Error example

`tsx
{
data: undefined,
error: [ConnectedSolutionsClientAuthError]: User Not Authorized
at ft.St [as generateError] (file:/stack/trace/path)
at k.fetchRequest (file:/stack/trace/path)
at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
at async k.fetchWithAuth (file:/stack/trace/path)
at async file:/stack/trace/path {
data: {
type: AUTHENTICATION_ERROR,
dev_url: 'https://experian.com/unity/docs/UNAUTHORIZED',
code: 'UNAUTHORIZED',
message: 'User Not Authorized'
},
status: 401
},
meta: {
status: 401,
statusText: 'User Not Authorized'
}
}
`

$3

* #### Retrieve all alerts

`tsx
await sdk.alerts.getAlerts();
`

* #### Retrieve a single alert

`tsx
await sdk.alerts.getAlertById({ id: 'alr_01' });
`

* #### Retrieve counts for all alerts

`tsx
await sdk.alerts.getAlertCounts();
`

* #### Mark an alert as read

`tsx
await sdk.alerts.markAlertAsRead({ id: 'alr_01' });
`

$3

The Credit Attributes API supports both v1 and v2 endpoints with different response formats. Use the version parameter to specify which API version to use. Leaving blank defaults to v1

* #### Retrieve attribute data for all historical reports

`tsx
// Defaults to V1
await sdk.creditAttributes.getCreditAttributes();

// V1 API - returns array of CreditAttributes objects
await sdk.creditAttributes.getCreditAttributes({ version: 'v1' });

// V2 API - returns CreditAttributes3B object with items array
await sdk.creditAttributes.getCreditAttributes({ version: 'v2' });
`

#### Credit Attribute version response validation

`tsx
import { isV1GetCreditAttributesResponse, isV2GetCreditAttributesResponse } from '@experian-ecs/connected-api-sdk'

const { data, error } = await sdk.creditAttributes.getCreditAttributes({
version: 'v2'
});

if (data) {
if (isV2GetCreditAttributesResponse(data)) {
// TypeScript now knows data is CreditAttribute3B
const { items } = data;
items.forEach(item => {
console.log(Attribute ID: ${item.id});
item.bureau_attributes.forEach(attribute => {
console.log(Bureau: ${attribute.bureau}, Reported At: ${attribute.reported_at}, Categories: ${attribute.categories}, Attributes: ${attribute.attributes});
});
});
} else if (isV1GetCreditAttributesResponse(data)) {
// TypeScript now knows data is CreditAttribute[]
data.forEach(attribute => {
console.log(Bureau: ${attribute.bureau}, Reported At: ${attribute.reported_at}, Categories: ${attribute.categories}, Attributes: ${attribute.attributes});
});
}
} else {
console.error(error);
}
`

$3

The Credit Reports API supports both v1 and v2 endpoints with different response formats. Use the version parameter to specify which API version to use. Leaving blank defaults to v1

* #### Retrieve all historical reports

`tsx
// Defaults to v1
await sdk.creditReports.getReports({
product_config_id: 'procfg_01',
include_fields: 'report_display',
})

// Version specific v1
await sdk.creditReports.getReports({
version: 'v1',
product_config_id: 'procfg_01',
include_fields: 'report_display',
});

// Version specific v2
await sdk.creditReports.getReports({
version: 'v2',
product_config_id: 'procfg_01',
report_date: '2025-09-01',
});
`

* #### Retrieve a single report

`tsx
await sdk.creditReports.getReportById({
id: '',
include_fields: 'report_display',
});

// Version specific v2
await sdk.creditReports.getReportById({
id: '1234',
version: 'v2'
});
`

* #### Retrieve all historical report summaries

`tsx
await sdk.creditReports.getReportMeta();

// Version specific v2
await sdk.creditReports.getReportMeta({
version: 'v2',
latest_only: true
});
`

* #### Retrieve a single report summary

`tsx
await sdk.creditReports.getReportMetaById({ id: '' });

// Version specific v2
await sdk.creditReports.getReportMetaById({
id: '123',
version: 'v2'
});
`

* #### Order a new report

`tsx
await sdk.creditReports.orderReport({
product_config_id: 'procfg_01',
include_fields: 'report_display',
});

// Version specific v2
await sdk.creditReports.orderReport({
version: 'v2',
product_config_id: 'procfg_01',
});
`

* #### Mark a report as read

`tsx
await sdk.creditReports.markReportAsRead({
id: '',
include_fields: 'report_display',
});

// Version specific v2
await sdk.creditReports.markReportAsRead({
version: 'v2',
id: '1234',
disposition: { read_status: 'READ' }
});
`

$3

The Credit Scores API supports both v1 and v2 endpoints with different response formats. Use the version parameter to specify which API version to use. Leaving blank defaults to v1

* #### Retrieve all historical scores

`tsx
// Defaults to V1
await sdk.creditScores.getCreditScores();

// V1 API - returns array of CreditScore objects
await sdk.creditScores.getCreditScores({ version: 'v1' });

// V2 API - returns CreditScore3B object with items array
await sdk.creditScores.getCreditScores({ version: 'v2' });
`

* #### Retrieve all historical scores with factors information

`tsx
await sdk.creditScores.getCreditScores({ include_factors: true });
`

* #### Retrieve all historical scores with ingredients information - FICO Only

`tsx
await sdk.creditScores.getCreditScores({ include_ingredients: true });
`

* #### Order a new score

`tsx
// Defaults to V1
await sdk.creditScores.orderCreditScore({
product_config_id: 'procfg_01'
});

// V2 API
await sdk.creditScores.orderCreditScore({
product_config_id: 'procfg_01',
version: 'v2'
});
`

* #### Credit Score version response validation

`tsx
import { isV1GetCreditScoresResponse, isV2GetCreditScoresResponse } from '@experian-ecs/connected-api-sdk'

const { data, error } = await sdk.creditScores.getCreditScores({
version: 'v2'
});

if (data) {
if (isV2GetCreditScoresResponse(data)) {
// TypeScript now knows data is CreditScore3B
const { items } = data;
items.forEach(item => {
console.log(Score ID: ${item.id});
item.bureau_scores.forEach(score => {
console.log(Bureau: ${score.bureau}, Score: ${score.score});
});
});
} else if (isV1GetCreditScoresResponse(data)) {
// TypeScript now knows data is CreditScore[]
data.forEach(score => {
console.log(Score ID: ${score.score_id}, Score: ${score.score});
});
}
} else {
console.error(error);
}
`

$3

* #### Get current plan

`tsx
await sdk.creditScorePlanner.getCreditScorePlan({
product_config_id: 'procfg_01'
});
`

* #### Get timeline options for creating a plan

`tsx
// FICO
await sdk.creditScorePlanner.getCreditScorePlanRevisions({
product_config_id: 'procfg_01',
target_score: 800
});

// VANTAGE
await sdk.creditScorePlanner.getCreditScorePlanRevisions({
product_config_id: 'procfg_01',
max_actions_per_plan: 5
});
`

* #### Create a new plan

`tsx
const { data, error } = await sdk.creditScorePlanner.getCreditScorePlanRevisions({
product_config_id: 'procfg_01',
target_score: 800,
})

if(data) {
const [ selectedRevision, ...revisions ] = data;

await sdk.creditScorePlanner.createCreditScorePlan({
product_config_id: 'procfg_01',
...selectedRevision
});

} else {
console.error(error)
}
`

* #### Delete your current plan

`tsx
await sdk.creditScorePlanner.deleteCreditScorePlan({
product_config_id: 'procfg_01'
});
`

$3

* #### Get all scenarios available for simulation

Vantage will return both the simulations and their simulated results from this method.

FICO will return only the possible simulations, and will require an additional call to simulateScenario to get the results of the selected simulation. Example below.

`tsx
await sdk.creditScoreSimulator.getSimulations({
product_config_id: 'procfg_01'
});
`

* #### Simulate a scenario - FICO Only

`tsx
import { isFicoScenario } from '@experian-ecs/connected-api-sdk'

const { data, error } = await sdk.creditScoreSimulator.getSimulations({
product_config_id: 'procfg_01'
})

if(data){
const {
simulations: [ selectedScenario, ...simulations ]
} = data;

if(isFicoScenario(selectedScenario)){
const { scenario, variations } = selectedScenario;

const simulationResult = await sdk.creditScoreSimulator.simulateScenario({
product_config_id: 'procfg_01',
scenario,
variations
})
}
} else {
console.error(error)
}
`

$3

* #### Retrieve knowledge based authentication questions

`tsx
const questionsRequest = await sdk.customerAuth.getAuthQuestions();
`

* #### Submit answers to knowledge based authentication questions

`tsx
await sdk.customerAuth.submitAuthAnswers({
answers: [
{
answer_order: 1,
choice_id: '1',
},
{
answer_order: 2,
choice_id: '2',

},
],
authentication_id: questionsRequest.authentication_id,
authentication_session_id: questionsRequest.authentication_session_id
})
`

$3

* #### Retrieve a customer

`tsx
await sdk.customers.getCustomerById({ customer_id: 'cus_01' });
`

* #### Update a customer

`tsx
await sdk.customers.updateCustomer({
customer_id: 'cus_01',
first_name: '';
// any other customer fields
});
`

* #### Delete a customer

`tsx
await sdk.customers.deleteCustomer({ customer_id: 'cus_01' });
`

* #### Search customers by fields

`tsx
await sdk.customers.searchCustomers({
count: 10,
name: { first_name: 'John' },
});
`

* #### Create a new customer

`tsx
await sdk.customers.createCustomer({
people_id: '',
reference_id: '',
first_name: '',
middle_initial: '',
last_name: '',
suffix: '',
addresses: [
{
address_type: 'CURRENT_RESIDENTIAL',
address1: '',
address2: '',
city: '',
state: '',
zip: '',
country_code: 'US',
},
],
phones: [
{
phone_type: 'HOME',
phone_country_code: '001',
phone_number: '123-494-3566',
},
],
emails: [
{
email_type: 'PERSONAL',
email_address: 'test@experian.com',
},
],
social_security_number: '',
date_of_birth: 'yyy-mm-dd',
outside_auth: false,
disclosure: {
accepted_at: 'yyy-mm-ddT00:00:00.000+00:00',
},
});
`

$3

* #### Retrieve all entitlements for a customer

`tsx
await sdk.entitlements.getEntitlements({ customer_id: 'cus_01' })
`

* #### Retrieve an entitlement by id

`tsx
await sdk.entitlements.getEntitlementById({ entitlement_id: 'ent_01' })
`

* #### Create a new entitlement for a customer with one or more products

`tsx
await sdk.entitlements.createEntitlement({
name: '',
description: '',
product_config_ids: [
'procfg_01'
];
customer_id: 'cus_01';
})
`

* #### Update an existing entitlement for a customer

`tsx
await sdk.entitlements.updateEntitlement({
entitlement_id: 'ent_01',
product_config_ids: [
'procfg_01'
];
customer_id: 'cus_01';
});
`

* #### Delete an entitlement

`tsx
await sdk.entitlements.deleteEntitlement({ entitlement_id: '' });
`

* #### Activate an exisiting entitlement

`tsx
await sdk.entitlements.activateEntitlement({ entitlement_id: '' });
`

* #### Deactivate an exisiting entitlement

`tsx
await sdk.entitlements.deactivateEntitlement({ entitlement_id: '' });
`

* #### Entitle customer to a new product

`tsx
await sdk.entitlements.entitleCustomerToNewProduct({
entitlement_id: 'ent_01',
product_config_id: 'procfg_01',
customer_id: 'cus_01'
});
`

* #### Activate a product already entitled to a customer

`tsx
await sdk.entitlements.activateProduct({
product_config_id: 'procfg_01',
entitlement_id: 'ent_01'
});
`

* #### Deactivate a product already entitled to a customer

`tsx
await sdk.entitlements.deactivateProduct({
product_config_id: 'procfg_01',
entitlement_id: 'ent_01'
});
`

* #### Remove a product entitled to a customer

`tsx
await sdk.entitlements.removeProductFromEntitlement({
product_config_id: 'procfg_01',
entitlement_id: 'ent_01'
});
`

* #### Get the eligibility status for an existing product entitled to a customer

`tsx
await sdk.entitlements.getProductEligibility({
product_config_id: 'procfg_01',
customer_id: 'cus_01'
});
`

$3

* #### Retrieve product configurations for a tenant

`tsx
await sdk.productConfigs.getProductConfigs();
`

* #### Retrieve a single product configuration for a tenant

`tsx
await sdk.productConfigs.getProductConfigById({
product_config_id: 'procfg_01'
});
`

$3

* #### Create a customer, create an entitlement, and activate product(s) in a single request

`tsx
await sdk.registrations.createRegistration({
customer: {
phones: [
{
phone_type: 'HOME',
phone_country_code: '',
phone_number: '',
},
],
date_of_birth: '',
last_name: '',
suffix: '',
social_security_number: '',
disclosure: {
accepted_at: 'yyyy-mm-ddT00:00:00.000+00:00',
},
emails: [
{
email_type: '',
email_address: '',
},
],
outside_auth: boolean,
middle_initial: '',
people_id: '',
addresses: [
{
address_type: '',
address1: '',
address2: '',
city: '',
state: '',
zip: '',
country_code: '',
},
],
reference_id: '',
first_name: '',
},
entitlement: {
name: '',
description: '',
available_at: 'yyyy-mm-ddT00:00:00.000+00:00',
product_config_ids: ['procfg_01'],
},
});
`

Utilities

$3

For typescript users, helper utility functions are exported in order to aid with type narrowing response types that return variable response models. An example use case can be viewed for simulating a credit score and validating credit score responses.

* Credit Score Planner

`tsx
function isPlanCompleted(plan: CreditScorePlan): plan is FicoCreditScorePlanCompleted | VantageCreditScorePlanCompleted;
function isPlanSet(plan: CreditScorePlan): plan is FicoCreditScorePlanCompleted | FicoCreditScorePlanSet | VantageCreditScorePlanCompleted | VantageCreditScorePlanSet;
function isVantagePlan(plan: CreditScorePlan): plan is VantageCreditScorePlan;
function isFicoPlan(plan: CreditScorePlan): plan is FicoCreditScorePlan;
function isFicoRevisionsRequest(request: ScorePlanRevisionsRequest): request is FicoScorePlanRevisionsRequest;
function isVantageRevisionsRequest(request: ScorePlanRevisionsRequest): request is VantageScorePlanRevisionsRequest;
function isFicoRevision(revision: ScorePlanRevision): revision is FicoScorePlanRevision;
function isVantageRevision(revision: ScorePlanRevision): revision is VantageScorePlanRevision;
`

* Credit Score Simulator

`tsx
function isFicoSimulator(data?: CreditScoreSimulator): data is FicoScoreSimulator;
function isVantageScenario(scenario?: Scenario): scenario is VantageScenario;
function isFicoScenario(scenario: Scenario): scenario is FicoScenario;
function isFicoScenarioVariation(variation?: ScenarioVariation): variation is FicoScenarioVariation;
function isVantageScenarioVariation(variation?: ScenarioVariation): variation is VantageScenarioVariation;
`

* Credit Scores

`tsx
function isValidApiVersion(version: string): version is ApiVersion;
function isCreditScore(data: unknown): data is CreditScore;
function isCreditScoreV2(data: unknown): data is CreditScore_V2;
function isBureauScore(data: unknown): data is BureauScore;
function isValidBureau(bureau: unknown): bureau is Bureau;
function isCreditScore3B(data: unknown): data is CreditScores_V2;
function isCreditScoreArray(data: unknown): data is CreditScore[];
function isV1GetCreditScoresResponse(data: unknown): data is GetCreditScoreResponse<'v1'>;
function isV2GetCreditScoresResponse(data: unknown): data is GetCreditScoreResponse<'v2'>;
function isV1PostCreditScoresResponse(data: unknown): data is PostCreditScoreResponse<'v1'>;
function isV2PostCreditScoresResponse(data: unknown): data is PostCreditScoreResponse<'v2'>;
`

* Credit Attributes

`tsx
function isCreditAttribute(data: unknown): data is CreditAttributes;
function isCreditAttributeV2(data: unknown): data is CreditAttribute_V2;
function isBureauAttribute(data: unknown): data is BureauAttribute;
function isValidBureauAttribute(bureau: unknown): bureau is Bureau;
function isCreditAttributesV2(data: unknown): data is CreditAttribute_V2;
function isCreditAttributeArray(data: unknown): data is CreditAttribute[];
function isV1GetCreditAttributesResponse(data: unknown): data is GetCreditAttributeResponse<'v1'>;
function isV2GetCreditAttributesResponse(data: unknown): data is GetCreditAttributeResponse<'v2'>;
``