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

NodeJs

• Instantiate the sdk

  import { createSDK } from '@experian-ecs/connected-api-sdk'
  
  // environment can either be 'PRODUCTION' or 'SANDBOX'
  const sdk = createSDK({ environment: 'PRODUCTION' })

• Retrieve an access token

  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

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

Browser

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

  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

Response format

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

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

• Success example

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

• Error example

  {
    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' 
    }
  }

Alerts

• Retrieve all alerts

  await sdk.alerts.getAlerts();

• Retrieve a single alert

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

• Retrieve counts for all alerts

  await sdk.alerts.getAlertCounts();

• Mark an alert as read

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

Credit Attributes

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

  // 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

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);
}

Credit Reports

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

  // 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

  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

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

• Retrieve a single report summary

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

• Order a new report

  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

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

Credit Scores

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

  // 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

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

• Retrieve all historical scores with ingredients information - FICO Only

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

• Order a new score

  // 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

  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);
  }

Credit Score Planner

• Get current plan

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

• Get timeline options for creating a plan

  // 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

  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

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

Credit Score Simulator

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

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

• Simulate a scenario - FICO Only

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

Customer Auth

• Retrieve knowledge based authentication questions

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

• Submit answers to knowledge based authentication questions

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

Customers

• Retrieve a customer

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

• Update a customer

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

• Delete a customer

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

• Search customers by fields

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

• Create a new customer

  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: '[email protected]',
      },
    ],
    social_security_number: '',
    date_of_birth: 'yyy-mm-dd',
    outside_auth: false,
    disclosure: {
      accepted_at: 'yyy-mm-ddT00:00:00.000+00:00',
    },
  });

Entitlements

• Retrieve all entitlements for a customer

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

• Retrieve an entitlement by id

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

• Create a new entitlement for a customer with one or more products

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

• Update an existing entitlement for a customer

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

• Delete an entitlement

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

• Activate an exisiting entitlement

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

• Deactivate an exisiting entitlement

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

• Entitle customer to a new product

  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

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

• Deactivate a product already entitled to a customer

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

• Remove a product entitled to a customer

  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

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

Product Configs

• Retrieve product configurations for a tenant

  await sdk.productConfigs.getProductConfigs();

• Retrieve a single product configuration for a tenant

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

Registrations

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

  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

Type Guards

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

  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

  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

  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

  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'>;