Credit Report Structure

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 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": [ { } ],
    ...
  }
}

Account Identification

The CREDIT_LIABILITY array contains an entry for each credit account 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 all three bureaus contribute, and if all three bureaus are aware of the same account, then that account will appear as three separate entries in the CREDIT_LIABILITY array.

You can correlate an account, as reported by a particular bureau, across multiple credit reports 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 bureau. Continuing our example, the three CREDIT_LIABILTY entries that represent the same account will each have a unique TradelineHashComplex property.

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.

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 Payment Status (Payment History)

The payment status on an account -- current, 30 days late, sent to collections, and so on -- 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": "7321CC221C2211C3221CCC1CCCC",
      "@_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 statment 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.

CharacterMeaning
CThe account is current
1-6The account is 1-6 billing cycles (30x days) late.
7The account is part of a Chapter 13 bankruptcy.
8The collateral for the account has been repossessed.
9The account is in collections.
NNo activity for this period.
XNo data for this period.

If we look at the payment pattern in the example, we see that the borrower struggled to keep the account current but it ultimately fell into bankruptcy (keep in mind that the pattern is in reverse chronological order):

Statement DateCharacterAccount Status
2021-10-207The account has been added to a Chapter 13 bankruptcy.
2021-09-203The account is 90 days late.
2021-08-202The account is 60 days late.
2021-07-201The account is 30 days late.
2021-06-20CThe account is current.
2021-05-20CThe account is current.
2021-04-202The account is 60 days late.
2021-03-202The account is 60 days late.
2021-02-201The account is 30 days late.
2021-01-20CThe account is current.

...and so on.

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