How to Retrieve a Credit Report
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 tohttps://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 theuserToken
value that we retrieved from Submit Customer's Answers. -
We set the
content-type
header toapplication/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
anddisplayToken
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).
Updated 10 months ago