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

See Credit Account Identification

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.

CharacterMeaning
CThe account is current
1-6The account has been late for 1-6 billing cycles.
7The account is part of a Chapter 13 bankruptcy.
8The collateral for the account has been repossessed.
9The account is in collections.
JThe account was voluntarily surrendered.
NNo activity for this period.
X, YNo data for this period.

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

1496

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