🚧
TransUnion information may not be transmitted by Array to Array clients or third parties, nor may Array clients access, view, share, process, or store TransUnion information.

This tutorial steps you through the process of using the Array API to retrieve a credit report for a customer. The code in this tutorial differs from a production application in three significant ways:

The API calls in this tutorial are sent to https://sandbox.array.io, the Array sandbox test site. In a real application, you send API calls to https://array.io.
When you're creating and testing your application, you can use any of the identities that are listed in Sandbox Identities. The customer that we're going to use ("Thomas Friedman") is a test account that's defined by TransUnion. In a production application you would, of course, retrieve a credit report for an actual customer.
The tutorial uses the Authenticate API to verify Thomas Friedman's identity. In a real application running in production, you would never use the Authenticate API. Instead, you would let your app's UI drive authentication by presenting the Account Enroll or Authenticate KBA component to the customer.

This tutorial introduces five APIs, invoked in this order:

First, we'll Create a User object that represents Thomas Friedman.
Next, we'll verify the authenticity of the information in the User object by calling Retrieve Authentication Questions followed by...
...Submit Customer's Answers. These are the two APIs that you never call in production; as mentioned above, you use the Array components, instead.
After the customer has been authenticated, we'll Order a Credit Report.
Finally, we'll call Retrieve HTML Credit Report to retrieve the credit report in HTML.

Create a User

First, we create a User object that corresponds to the "Thomas Friedman" test persona by calling Create a User. In cURL, the call looks like this:

curl -X POST "https://sandbox.array.io/api/user/v2" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "appKey": "3F03D20E-5311-43D8-8A76-E4B5D77793BD",
            "firstName": "Thomas",
            "lastName": "Friedman",
            "ssn": "666234390",
            "dob": "1975-01-01",
            "address": {
              "state": "CO",
              "street": "535 30 RD A",
              "city": "Grand Junction",
              "zip": "81504"
            }
          }'

The appKey value used here represents a public sandbox application. Although you can use it when you're getting a feel for how the Array API works, you should use your own appKey when you're testing your app. The rest of the data is taken from Sandbox Identities.

Response

If the call is successful, the response body will contain a clientKey property. You'll use this property in subsequent API calls. You can ignore the other properties.

{
  "clientKey":"EE0F2D0F-DC2B-43BE-9BA8-1990E2B09EB7",
  // ignore the other properties
}

Retrieve Authentication Questions

Next, we ask an "authentication provider" (a credit bureau) to generate and return a set of questions and multiple choice answers that are based on Thomas Friedman's account. the Retrieve Authentication Questions operation to retrieve "knowledge-based authentication" questions and answers that are based on Thomas Friedman's credit report.

curl "https://sandbox.array.io/api/authenticate/v2\
?appKey=3F03D20E-5311-43D8-8A76-E4B5D77793BD\
&clientKey=EE0F2D0F-DC2B-43BE-9BA8-1990E2B09EB7\
&provider1=tui&provider2=efx&provider3=exp" \
     -H "Content-Type: application/json; charset=utf-8"

Again, we're using the public appKey, although now it's passed as a query parameter.
The clientKey query parameter takes the value that was returned by the Create a User call.
The providerN parameters list the authentication providers in the order that they'll be consulted. If the first provider (tui means TransUnion) doesn't recognize Thomas Friedman, the call will try the second provider (efx = Equifax), and then the third (exp = Experian).

Response

If the call is successful, the response will contain...

An authentication session token (authToken) that you'll need in the next call.
The identity of the provider that generated the questions (provider).
An array of authentication questions and multiple choice answers questions).

In this response snippet, we only display the first question in the questions array:

{
  "authToken": "8B57E8EF-6621-4981-89C3-67DB5CF0E8EF",
  "provider": "tui",
  "questions": [{
    "id": "57249086",
    "text": "Which of the following is a current or previous employer?",
    "answers": [{
      "id": "3119496498",
      "text": "American International Group"
    }, {
      "id": "3119496500",
      "text": "Iec"
    }, {
      "id": "3119496502",
      "text": "Paychex"
    }, {
      "id": "3119496504",
      "text": "Synovus"
    }, {
      "id": "3119496506",
      "text": "None of the Above"
    }]
  }, 
  // and so on for the other questions/answers
  ]
}

Submit Customer's Answers

To submit our answers to the authentication questions, we create an answers object that contains a key: value property for each of the entries in the questions array. The key is the id of the question; the value is the id of the answer that we've selected. We then post the answers array to the Submit Customer's Answers operation.

curl -X "POST" "https://sandbox.array.io/api/authenticate/v2" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "appKey": "3F03D20E-5311-43D8-8A76-E4B5D77793BD",
            "clientKey": "EE0F2D0F-DC2B-43BE-9BA8-1990E2B09EB7",
            "authToken": "8B57E8EF-6621-4981-89C3-67DB5CF0E8EF",
            "answers": {
              "57249086": "3119496500",
              "57249094": "3119496702",
              "57249102": "3119496814",
              // and so on for the other questions/answers
            }
          }'

Notice that in addition to the answers object, we also must supply the appKey and clientKey values that we used in previous calls, and the authToken that was returned by Retrieve Authentication Questions.

How to Select a Correct Answer

We select our answers to the authentication questions by consulting the list of correct (case-insensitive) answers in Sandbox Identities: Authentication Answers.

For example, "IEC" is listed as a correct answer; the choices for the "Which of the following is a current or previous employer?" question shown in the previous section includes "Iec", so we create a key: value property using the IDs of the question (57249086) and answer (3119496500):

Response

If the answers are correct, the call returns 200 and a single userToken property that you'll use in the next step:

{
  "userToken": "2BDE764E-3641-4D18-930E-C7A3B41C2239"
}

Order a Credit Report

In this step, we'll Order a Credit Report that will contain data (including the credit score) from TransUnion.

We pass two headers and two body properties to the call:

The x-credmo-user-token header takes the userToken value that we retrieved from Submit Customer's Answers.
We set the content-type header to application/json.
Once again, we pass clientKey as a body property.
Finally, we use the productCode property to declare the type of report we want. tui1bReportScore means "TransUnion (only) Report and Score".


curl -X POST "https://sandbox.array.io/api/report/v2" \
     -H 'x-credmo-user-token: 2BDE764E-3641-4D18-930E-C7A3B41C2239' \
     -H 'content-type: application/json' \
     -d $'{
            "clientKey": "EE0F2D0F-DC2B-43BE-9BA8-1990E2B09EB7",
            "productCode": "tui1bReportScore"
          }'

Response

If the report is successfully ordered, the response will contain a reportKey and displayToken that we'll use to retrieve the report. For this tutorial, we're going to ignore the response's other properties.

{
  "reportKey": "692EE082-07C2-4C0F-A1C4-8266F2C4DAA4",
  "displayToken": "4771FFC0-1AD8-4E38-A8C0-058B09D79B28",
  // ignore the other properties
}

Retrieve a Credit Report

Finally, we retrieve a credit report as an HTML page by passing the reportKey and displayToken to the Retrieve HTML Credit Report.

🚧
The reportKey and displayToken tokens can only be used once. The tokens are invalidated after the report is retrieved.

## Report - Retrieve
curl "https://sandbox.array.io/api/report/v2/html\
?reportKey=692EE082-07C2-4C0F-A1C4-8266F2C4DAA4\
&displayToken=4771FFC0-1AD8-4E38-A8C0-058B09D79B28"

Response

Although the call returns immediately, the system could take some time -- usually no more than a few seconds -- to generate the report. A 202 HTTP status means that the API is still generating the report, in which case you should repeat the call until it returns 200 (success) or 204 (failure). The reportKey and displayToken will remain valid while you're making these iterated calls.

Other formats

In addition to HTML, you can retrieve a credit report as PDF, or as a JSON, XML, or raw data document).