Connected Experience API SDK
npm install @experian-ecs/connected-api-sdk1. 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
* #### 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
});
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'
})
`
* 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'
}
}
* #### 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' });
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});Bureau: ${attribute.bureau}, Reported At: ${attribute.reported_at}, Categories: ${attribute.categories}, Attributes: ${attribute.attributes}
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();`
});
}
} else {
console.error(error);
}
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' }
});
`
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});Bureau: ${score.bureau}, Score: ${score.score}
item.bureau_scores.forEach(score => {
console.log();Score ID: ${score.score_id}, Score: ${score.score}
});
});
} else if (isV1GetCreditScoresResponse(data)) {
// TypeScript now knows data is CreditScore[]
data.forEach(score => {
console.log();`
});
}
} else {
console.error(error);
}
* #### 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'
});
* #### 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)
}
`
* #### 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
})
`
* #### 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',
},
});
* #### 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'
});
* #### 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'
});
* #### 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'],
},
});
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'>;