@experian-ecs/connected-api-sdk

中文文档
1.7.0发布于 2026/04/23SEE LICENSE IN LICENSE.mdTypeScriptESM + CJS零依赖近 30 天下载 2.5万

Connected Experience API SDK

原始使用文档
文档目录20 节
  1. Authentication
  2. NodeJs
  3. Browser
  4. Usage
  5. Response format
  6. Alerts
  7. Credit Attributes
  8. Credit Reports
  9. Credit Scores
  10. Credit Score Planner
  11. Credit Score Simulator
  12. Customer Auth
  13. Customers
  14. Entitlements
  15. Identity Attributes
  16. Product Configs
  17. Offers
  18. Registrations
  19. Utilities
  20. Type Guards

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. Identity Attributes
    12. Product Configs
    13. Offers
    14. 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'
    });
    

Identity Attributes

  • Retrieve the monitoring profile

    await sdk.identityAttributes.retrieveMonitoringProfile();
    
  • Create a monitoring profile

    await sdk.identityAttributes.createMonitoringProfile({
      emails: [{ value: '[email protected]' }],
      phones: [{ value: '123-456-7890' }],
      social_security_numbers: [{ value: '123-45-6789' }],
    });
    
  • Add items to existing monitoring profile

    await sdk.identityAttributes.createNewMonitoringProfileItem({
      emails: [{ value: '[email protected]' }],
    });
    
  • Update monitored items

    await sdk.identityAttributes.updateMonitoringProfile({
      emails: [{ id: 'cyb_01JFDHF00Y349X79EYXGFB25K7', value: '[email protected]' }],
    });
    
  • Delete monitored items

    await sdk.identityAttributes.deleteMonitoringProfile({
      emails: ['cyb_01JFDHF00Y349X79EYXGFB25K7'],
    });
    

Product Configs

The Product Config 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 product configurations for a tenant

    // Defaults to V1
    await sdk.productConfigs.getProductConfigs();
    
    // V1 API - returns product configurations
    await sdk.productConfigs.getProductConfigs({version: 'v1'});
    
    // V2 API - Includes Score Ranges and Disclosures array
    await sdk.productConfigs.getProductConfigs({version: 'v2'});
    
  • Retrieve a single product configuration for a tenant

    // Defaults to V1
    await sdk.productConfigs.getProductConfigById({ 
      product_config_id: 'procfg_01' 
    });
    
    // V1 API
    await sdk.productConfigs.getProductConfigById({ 
      product_config_id: 'procfg_01',
      version: 'v1'
    });
    
    // V2 API - Includes Score Ranges and Disclosures array
    await sdk.productConfigs.getProductConfigById({ 
      product_config_id: 'procfg_01',
      version: 'v2' 
    });
    

Offers

  • Retrieve available credit card offers

    await sdk.offers.getOffers({
      product_config_id: 'procfg_01'
    });
    
  • Handle a successful empty offers response

    const { data, error } = await sdk.offers.getOffers({
      product_config_id: 'procfg_01'
    });
    
    if (data && data.offer_summary.total_count === 0) {
      console.log('No offers available');
    } else if (error) {
      console.error(error);
    }
    

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

版本与发布记录

@experian-ecs/connected-api-sdk 共发布 10 个版本,首次发布于 2025/03/12;过去 12 个月发布了 4 个版本。

版本发布日期距今
1.7.0latest2026/04/236 个月前
1.6.02026/04/017 个月前
1.5.02026/03/128 个月前
1.4.02026/02/248 个月前
1.3.02025/10/011.1 年前
1.2.02025/08/081.3 年前

关于 @experian-ecs/connected-api-sdk 的常见问题

@experian-ecs/connected-api-sdk 是什么?

Connected Experience API SDK

如何安装 @experian-ecs/connected-api-sdk?

在项目目录运行 npm install @experian-ecs/connected-api-sdk,或使用 pnpm add / yarn add / bun add。

@experian-ecs/connected-api-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@experian-ecs/connected-api-sdk 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@experian-ecs/connected-api-sdk 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20.x.x。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@experian-ecs/connected-api-sdk 可以商用吗?

@experian-ecs/connected-api-sdk 使用 SEE LICENSE IN LICENSE.md 许可。许可条款写在包内的独立文件中,请阅读该文件确认可否商用。以上为概括,不构成法律意见,请以许可原文为准。

@experian-ecs/connected-api-sdk 的下载量有多少?

根据 npm 官方下载统计,@experian-ecs/connected-api-sdk 在 2026/10/14 – 2026/11/12 这 30 天内被下载 24,684 次,日均约 823 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@experian-ecs/connected-api-sdk 还在维护吗?

最新版本 1.7.0 发布于 2026/04/23(6 个月前);至今共发布 10 个版本,其中过去 12 个月发布了 4 个;首次发布于 2025/03/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。