This document looks at the composition of a structured credit report (XML or JSON) that's generated and returned by the Retrieve a Credit Report operation. The composition is based on the MISMO 2.4 Credit Reporting standard, to which Array has added a small number of custom attributes. While documenting the entire MISMO structure is beyond the scope of this documentation, we'll take a look at the general outline of the structure, describe some of the notable elements, and provide guidance for processing the report data.

General Structure

A structured credit report contains a single top-level element, CREDIT_RESPONSE, that contains all of the other elements:

{
  "CREDIT_RESPONSE":
  {
    "@MISMOVersionID": "2.4",
    "@CreditResponseID": "CRRep0001",
    "@CreditReportIdentifier": "2-cc74ac77-ca9d-41aa-9",
    
    "CREDIT_REPOSITORY_INCLUDED": { },
    "CREDIT_FROZEN_STATUS":  { },
    "CREDIT_LIABILITY": [ { } ],
    ...
  }
}

JSON Arrays and Objects

Some credit report elements can take multiple values. For example, a borrower can have more than one employer (past and present). In XML, there's no structural difference between an element with a single value and an element with multiple values: Each value is presented as an independent element.

In JSON, however, it's not that simple. If a borrower has only one employer, the EMPLOYER property in the borrower's credit report is presented as a single object (i.e., it isn't an array):

"EMPLOYER": 
{
  "@_Name": "NATIONAL GUARD",
  "@EmploymentCurrentIndicator": "Y",
  "@EmploymentReportedDate": "2020-11-21"
}

But if the borrower has multiple employers, the EMPLOYER property becomes an array:

"EMPLOYER": 
[
  {
    "@_Name": "NATIONAL GUARD",
    "@EmploymentCurrentIndicator": "Y",
    "@EmploymentReportedDate": "2020-11-21"
  },
  {
    "@_Name": "ARMY",
    "@EmploymentCurrentIndicator": "N",
    "@EmploymentPositionDescription": "HVAC TECH",
    "@EmploymentReportedDate": "2018-02-03"
  }
],

This means that if you're processing the JSON version of a credit report, you have to determine whether the property's value is an object or an array before you can process it.

How to Determine Which Bureaus Have Contributed

The CREDIT_REPOSITORY_INCLUDED element indicates whether or not a particular bureau has contributed to the report. For example, here we see that Experian and TransUnion have contributed, but Equifax has not:

"CREDIT_REPOSITORY_INCLUDED": 
{
  "@_EquifaxIndicator": "N",
  "@_ExperianIndicator": "Y",
  "@_TransUnionIndicator": "Y"
}

CREDIT_REPOSITORY_INCLUDED is a standard MISMO element.

How to Determine If Credit is Frozen (or "Locked")

The CREDIT_FROZEN_STATUS element is an Array addition to the MISMO standard:

"CREDIT_FROZEN_STATUS":
{
  "@_EquifaxIndicator": "true",
  "@_ExperianIndicator": "",
  "@_TransUnionIndicator": "false"
}

Each of the element's properties provides the named bureau's assessment of whether the borrower's credit is frozen (true) or not (false). If the bureau isn't contributing to the report, the value is "".

Account Identification and Correlation

The CREDIT_LIABILITY array lists the credit accounts that the customer is responsible for. Furthermore, each bureau contributes an entry for every account that it's aware of. If you're generating a report to which multiple bureaus have contributed (a "2B" or "3B" report), then the same account will almost certainly appear multiple times. The Correlating Accounts within a Single Report section, below, tells you how to correlate CREDIT_LIABILITY entries that denote the same account within a single credit report.

You may also need to correlate accounts across credit reports pulled at different times. While the real world account number that the customer recognizes will stay the same, the identifier value that's brought back in the report (through the @_AccountIdentifier property) isn't reliable: The same bureau can obfuscate the value differently at different times. Correlating Accounts across Multiple Reports tells you how to correlate accounts across multiple credit reports that are pulled over time.

Correlating Accounts within a Single Report

In a multiple bureau credit report, the same account will appear multiple times in the CREDIT_LIABILITY array, once for each bureau that recognizes the account. In addition to each of these bureau-specific appearances, the account's information is merged in yet another entry. Thus, for a 2B report, you'll see the account three times; for a 3B, it will appear four times.

For example, here's what the CREDIT_LIABILTY entries for the same account look like in a 3B report (with lots of information snipped for brevity):

{
  "@CreditLiabilityID": "TRADE001",
  "@CreditTradeReferenceID": "Primary",
  "@_AccountIdentifier": "35469083265902",
  "@_AccountOpenedDate": "2017-12-02",
  "CREDIT_REPOSITORY": [
    { "@_SourceType": "Equifax" },
    { "@_SourceType": "Experian" },
    { "@_SourceType": "TransUnion" }
  ]
},
{
  "@CreditLiabilityID": "TRADE002",
  "@CreditTradeReferenceID": "Secondary",
  "@_AccountIdentifier": "35469083265902",
  "@_AccountOpenedDate": "2017-12-02",
  "CREDIT_REPOSITORY": { "@_SourceType": "Equifax" }
},
{
  "@CreditLiabilityID": "TRADE003",
  "@CreditTradeReferenceID": "Secondary",
  "@_AccountIdentifier": "35469083265902",
  "@_AccountOpenedDate": "2017-12-02",
  "CREDIT_REPOSITORY": {"@_SourceType": "TransUnion"}
},
{
  "@CreditLiabilityID": "TRADE004",
  "@CreditTradeReferenceID": "Secondary",
  "@_AccountIdentifier": "354690XXXXXXXX",
  "@_AccountOpenedDate": "2017-12-02",
  "CREDIT_REPOSITORY": { "@_SourceType": "Experian" }
}

First, notice the values of the @_AccountIdentifier properties. You would expect them all to be the same, but they're not. While Equifax and TransUnion provide the full account number, Experian obfuscates it. This means that you can't rely on the @_AccountIdentifier value as a way to correlate accounts.

Now regard the values of the respective @CreditTradeReferenceID properties:

• In the first entry, the value is Primary. This is the merged version of the account.

• In the subsequent entries, the values are Secondary. These are the accounts as reported by the individual bureaus. The [email protected]_SourceType value identifies the bureau.

The entries' order and contiguity is important:

• The Secondary entries immediately follow the Primary entry.

Thus, to correlate a set of entries that denote the same account, you find a primary and then look at the immediately following secondaries.

In a 1B account, every entry is marked Primary -- there's no merged version (because it isn't needed). Similarly, if an account is recognized by only one of the bureaus in a multiple-bureau account, the account will have a single entry marked Primary.

Correlating Accounts across Multiple Reports

You can correlate an account across time by looking at the account's TradelineHashComplex property. The property is a permanent and unique identifier for an account that's owned by the customer and reported by a particular bureau. If an account is reported by all three bureaus, the multiple CREDIT_LIABILTY entries that represent the account, as explained in the previous section, will have unique TradelineHashComplex values, including the merged version.

Thus, to correlate accounts across multiple credit reports that you've pulled at different times, you look for identical TradelineHashComplex values. If the TradelineHashComplex property is missing, or if it doesn't yield a match across reports, you can use the TradelineHashSimple property. The latter isn't as foolproof as the former, so you may want to compare other properties (@_AccountOpenedDate, for example) as well.

Here's the Equifax entry from the previous section with the two hash properties:

{
  "@CreditLiabilityID": "TRADE002",
  "@CreditTradeReferenceID": "Secondary",
  "@_AccountIdentifier": "35469083265902",
  "@_AccountOpenedDate": "2017-12-02",
  "@TradelineHashComplex": "0e754b05d60c31bda5420294c7a536b8",
  "@TradelineHashSimple": "38401ec5f7ff1c11559c8dcb23dc363e",  
  "CREDIT_REPOSITORY": { "@_SourceType": "Equifax" }
}

Account Payment History

The history of payments (or non-payments) on an account is encoded in the _PAYMENT_PATTERN object that's part of the account's entry in the CREDIT_LIABILITY array. For example:

"CREDIT_LIABILITY":
[
  {
    ...
    "_PAYMENT_PATTERN":
    {
      "@_Data": "7321CC",
      "@_StartDate": "2021-10-20"
    },
    ...

The _PAYMENT_PATTERN object has two properties:

• @_DATA is a string of characters that represent the account status at each billing period (one character per period) in reverse chronological order (most recent billing period first).

• @_StartDate is the statement date of the most recent billing period -- in other words, it's the date of the leftmost character in the @_Data string. The date is in YYYY-MM-DD format.

The pattern characters are described below.

The illustration demonstrates how to read the payment pattern we saw in the example above.

Credit Summary

The CREDIT_SUMMARY property contains a list of attributes that can affect the borrower's credit score, attributes such as the number of accounts that the borrower is responsible for, the credit utilization across accounts that have been active in the past 12 months, the dollar amount of tax liens against the borrower, and so on. These "credit summary attributes" are listed in an array named _DATA_SET within CREDIT_SUMMARY; however, the location of _DATA_SET depends on whether or not TransUnion has contributed to the report:

• If TransUnion has contributed to the report, CREDIT_SUMMARY is an array that contains two objects, both of which have a _DATA_SET array. The object that contains the credit summary attributes is the one with the "@_Name": "Attributes" property. The other object, namedTransUnion Credit Summary, provides a very short list of attributes that are taken only from TransUnion.

• If TransUnion hasn't contributed to the report, CREDIT_SUMMARY is an object that contains the _DATA_SET array.

Here are examples of CREDIT_SUMMARY with and without TransUnion:

"CREDIT_SUMMARY": [
  {
    "@BorrowerID": "Borrower01",
    "@_Name": "Attributes", // THIS IS THE ONE YOU WANT
    "_DATA_SET": [
      {
        "@_ID": "AP001",
        "@_Value": "18",
        "@_Name": "Number of tradelines"
      },
      {
        "@_ID": "AP002",
        "@_Value": "54",
        "@_Name": "Average age of open tradelines"
      }
      ...
    ]
  },
  {
  "@BorrowerID": "Borrower01",
  "@_Name": "TransUnion Credit Summary", // SUMMARY OF TRANSUNION ATTRIBUTES, ONLY
  "_DATA_SET": [
    {
      "@_Name": "Number of Public Records",
      "@_Value": "000"
    },
    {
      "@_Name": "Number of Collections",
      "@_Value": "000"
    },
]

"CREDIT_SUMMARY": {
  "@BorrowerID": "Borrower01",
  "@_Name": "Attributes", 
  "_DATA_SET": [
    {
      "@_ID": "AP001",
      "@_Value": "18",
      "@_Name": "Number of tradelines"
    },
    {
      "@_ID": "AP002",
      "@_Value": "54",
      "@_Name": "Average age of open tradelines",
    }
    ...
  ]
}

Credit Summary Attribute Objects

Each credit summary attribute object contains three properties:

• @_ID is a string token that uniquely identifies the attribute. If you're comparing multiple credit reports, this is the property that you use to correlate attributes across the reports.
• @_Value is the value of the attribute. The value is always a string, even if the attribute is a count, a dollar amount, or some other measurable quantity.
• @_Name is a description of the attribute. It uses industry argot, so it shouldn't be presented to your customers. For descriptions that are more user-friendly, see Credit Summary Attributes