# Tenant Screening Tutorial
source: https://developer.mastercard.com/open-finance-us/documentation/tutorials/tenant-screening/index.md
## Overview {#overview}
Mastercard Open Finance solutions assist with multiple steps of the tenant screening flow, enabling you to verify recurring income, check current balances and identify rental payment history before approving a rental application.
For any tenant screening use case, we recommend you take the following steps:
* verify an applicant's recurring **income** sources and amounts to ensure an applicant can afford a potential rent payment.
* verify an applicant's current **balances** to ensure they have sufficient funds to cover a security deposit, first/last month rent requirements, etc. (optional)
* verify an applicant's **transaction history** to confirm their rental history and measure payment consistency (optional)
Additionally, if you also wish to facilitate monthly rental payments via account to account payments reference the [Pay by Bank Tutorial](https://developer.mastercard.com/open-finance-us/documentation/tutorials/pay-by-bank/index.md) for more information.
Note that while this tutorial explains how to get started with a tenant screening solution implementation, it assumes you have already gone through the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md). You will note that the additional steps explained below modify the primary experience highlighted in that guide to optimize for this specific use case. Additional information for the most common tenant screening products can be found in the
[Lend](https://developer.mastercard.com/open-finance-us/documentation/products/lend/index.md) product section.
## Creating a Consumer {#creating-a-consumer}
The most commonly used tenant screening products fall within the scope of Federal Credit Reporting Agency
(FCRA) protections and regulations. After you have created a `customerId` on our platform,
you must then create a a consumer record before you can generate and view CRA reports.
Unlike a customer record, a consumer record cannot be deleted. A copy of
the report created for a consumer will be available for six years. Unless
stated otherwise, all Lend products require a consumer record. There is a one-to-one relationship
between a customer record and a consumer record.
Prior to connecting accounts or generating a report, use the below endpoint to create a `consumerId` on our platform:
API Reference: `POST /decisioning/v1/customers/{customerId}/consumer`
Reference the following for more in depth information about the specifics to [create a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) record.
Note: When creating a consumer record, end user information must be provided by partners that are resellers. This is due to FCRA regulatory requirements.
## Mastercard Data Connect {#mastercard-data-connect}
The next step is to have the customer grant permission to connect their data.
This is done through the Mastercard Data Connect application. Data Connect supports linking bank accounts, payroll accounts, and uploading paystubs depending on the Data Connect experience used. See [the Data Connect documentation](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md) to learn more about the Data Connect experiences and how you can use them.
Data Connect Full experiences are commonly used for Lend products. Below is a list of Data Connect Full experiences. The Financial Institution (FI) certification and other settings are configured for best results for the report type(s) mentioned. Use the self-service [Data Connect customization tool](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md) within Client Hub or contact your Mastercard Account Manager for help configuring your Data Connect experience.
Tip: If a product is not available within the Data Connect customization tool, you can use the basic Aggregation Data Connect experience type to have the customer connect bank accounts, then you can directly generate the report yourself via the API. Reference the Alternative Flows section below for more detail.
To enable Data Connect, either embed a [Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-full-including-for-joint-borrower) into your experience, or [send a Data Connect email](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#send-data-connect-email)
to the customer. For best results, in the on-ramp to Data Connect, prepare the customer by letting them know the benefits of digitally connecting their accounts and remind them what account types to connect. Once in Data Connect, the customer is prompted to link their accounts.
If you have a use case where there are multiple customers applying for a loan jointly, you can use our [Data Connect Full -- Joint Borrower](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md#data-connect-full-including-for-joint-borrower) flow.
Multiple customer IDs and consumer IDs can be tied together to one Data Connect experience. Bank accounts are connected and linked to the customer/consumer record tied to the customer designated as the "primary" borrower. Payroll accounts are connected individually per borrower.
For more information, see the [Data Connect application documentation](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md), and the [UX implementation best practices](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/index.md).
Note: We highly recommend including a `callbackUrl` in your Generate Data Connect URL request so we can send a webhook event informing you when report generation is complete to your [webhook listener](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/webhooks-events-report/index.md).
## Generating a Report {#generating-a-report}
Your Mastercard Data Connect experience should be configured to automatically generate your preferred report or [Product Type](https://developer.mastercard.com/open-finance-us/documentation/connect/configure-connect-experience/customize-connect/index.md#product-type) as soon as the customer completes the account connection flow.
If you have configured a webhook listener, you will know the report is ready when a webhook notification with the `eventType` of `done` is sent. This will include the `customerId` and `id` for any generated reports. Store the report ID value as you will need it to get the report.
## Get Report(s) {#get-reports}
All reports can be fetched once they are ready using the same Get Report endpoints. You need the ID of the report that was returned when you
generated the report. Most reports can be retrieved in JSON or PDF
formats.
We recommend using the [Get Report by Report ID](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md#get-report-by-report-id)
endpoint, which enables you to retrieve a report with the report ID alone
without providing a customer or consumer ID. For other options, see [Getting Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md).
API Reference: `POST /decisioning/v3/reports/{reportId}`
### Verifying Income {#verifying-income}
The [Verification of Income (VOI)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voi/index.md) report analyzes both active and inactive income streams, and then ranks them with a confidence score. It retrieves up to 24 months of validated banking data for an individual customer, based on the accounts they have permissioned to access.
The following example shows a successful JSON response when requesting a VOI report:
```json
{
"id": "u4hstnnaewetr-voi",
"customerId": 1000006677,
"consumerId": "ac39e237c7619a4ecf014b8d399c0696",
"consumerSsn": "6789",
"disputeStatement": "Invalid data present.",
"requesterName": "Decisioning API",
"endUser": {
"name": "ABC Apartments",
"address": "123 Main St",
"city": "Murray",
"state": "UT",
"zip": "84123",
"phone": "555-2106",
"email": "customerservice@example.com",
"url": "example.com"
},
"requestId": "sfb7xp4wer",
"type": "voi",
"status": "success",
"createdDate": 1588350269,
"customerType": "active",
"title": "Mastercard Open Banking Verification of Income",
"startDate": 1572625469,
"endDate": 1588350269,
"days": 200,
"seasoned": true,
"portfolioId": "dyr6qvqd2erw-1-port",
"institutions": {
"id": 101732,
"name": "FinBank",
"urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp",
"accounts": {
"id": 1000023996,
"number": "1111",
"ownerName": "JOHN DOE",
"ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518",
"ownerAsOfDate": 1577986990,
"name": "Checking",
"type": "checking",
"aggregationStatusCode": 0,
"incomeStreams": {
"id": "dens28i3vsch-voi1",
"name": "none",
"status": "ACTIVE",
"estimateInclusion": "MODERATE",
"confidence": 70,
"cadence": {
"startDate": 1577986990,
"stopDate": 1587986990,
"days": 14
},
"netMonthly": [
{
"month": 1522562400,
"net": 2004.77
}
],
"netAnnual": 110475.7,
"projectedNetAnnual": 0,
"estimatedGrossAnnual": 0,
"projectedGrossAnnual": 151609,
"averageMonthlyIncomeNet": 9206.31,
"incomeStreamMonths": 18,
"transactions": [
{
"id": 100000527471,
"amount": 22.21,
"postedDate": 1582286400,
"description": "FINICITY INC PAYROLL",
"memo": "Finicity amount credit",
"institutionTransactionId": "100000000",
"category": "Paycheck"
}
]
},
"balance": 714.16,
"averageMonthlyBalance": 720.75,
"transactions": [],
"availableBalance": 714.16,
"currentBalance": 714.16,
"beginningBalance": 714.77,
"miscDeposits": [
{
"id": 100000527471,
"amount": 22.21,
"postedDate": 1582286400,
"description": "FINICITY INC PAYROLL",
"memo": "Finicity amount credit",
"institutionTransactionId": "100000000",
"category": "Paycheck"
}
]
}
},
"income": [
{
"confidenceType": "MODERATE",
"netMonthly": [
{
"month": 1522562400,
"net": 2004.77
}
],
"incomeEstimate": {
"netAnnual": 1000.12,
"projectedNetAnnual": 1500.23,
"estimatedGrossAnnual": 2000.12,
"projectedGrossAnnual": 2500.23
}
}
]
}
```
How to read a VOI PDF report:
[VOI_Report_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOI_Report_HTR.pdf) (2MB)
### Balance Analytics {#balance-analytics}
The [Balance Analytics (BA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/balance-analytics/index.md) report provides insights into a customer's account balances over time, helping assess liquidity, trends, and potential risk for lending and portfolio decisions. BA analyzes up to 24 months of transaction history (as available) and returns attributes such as minimum, maximum, and average balances over the desired time intervals.
The following example shows a successful JSON response when requesting a VOA report:
```json
{
"id": "u4hstnnak45g",
"customerId": 1000006677,
"consumerId": "ac39e237c7619a4ecf014b8d399c0696",
"consumerSsn": "6789",
"disputeStatement": "Invalid data present.",
"requesterName": "Decisioning API",
"endUser": {
"name": "ABC Apartments",
"address": "123 Main St",
"city": "Murray",
"state": "UT",
"zip": "84123",
"phone": "555-2106",
"email": "customerservice@example.com",
"url": "example.com"
},
"requestId": "sfb7xp439w",
"type": "voa",
"status": "success",
"createdDate": 1588350269,
"constraints": {
"accountIds": [
"1000535275",
"1000535276"
],
"fromDate": 1577986990,
"reportCustomFields": [
{
"label": "loanID",
"value": "12345",
"shown": true
},
{
"label": "trackingID",
"value": "5555",
"shown": true
},
{
"label": "loanType",
"value": "car",
"shown": false
},
{
"label": "vendorID",
"value": "1613aa23",
"shown": true
},
{
"label": "vendorName",
"value": "PSC Finance",
"shown": false
}
],
"showNsf": false
},
"customerType": "active",
"title": "Mastercard Open Banking Verification of Assets",
"startDate": 1572625469,
"endDate": 1588350269,
"days": 180,
"seasoned": false,
"consolidatedAvailableBalance": 2345,
"portfolioId": "dyr6qvqd2yhb-1-port",
"institutions": {
"id": 101732,
"name": "FinBank",
"urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp",
"accounts": {
"id": 1000023996,
"number": "1111",
"ownerName": "JOHN DOE",
"ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518",
"ownerAsOfDate": 1588350276,
"name": "Checking",
"type": "checking",
"availableBalance": 501.24,
"aggregationStatusCode": 0,
"balance": 501.24,
"balanceDate": 1588350276,
"averageMonthlyBalance": 501.02,
"totNumberInsufficientFundsFeeDebitTxAccount": 0,
"totNumberInsufficientFundsFeeDebitTxOver2MonthsAccount": 0,
"totNumberDaysSinceMostRecentInsufficientFundsFeeDebitTxAccount": 120,
"transactions": [
{
"id": 100000527471,
"amount": 22.21,
"postedDate": 1582286400,
"description": "FINICITY INC PAYROLL",
"memo": "Finicity amount credit",
"investmentTransactionType": "dividend",
"normalizedPayee": "Finicity",
"institutionTransactionId": "100000000",
"category": "Paycheck",
"bestRepresentation": "FINICITY INC PAYROLL"
}
],
"details": {
"interestMarginBalance": -50000,
"availableCashBalance": 1500,
"vestedBalance": 300000,
"currentLoanBalance": 0,
"availableBalanceAmount": 1000,
"marginBalance": 100,
"currentBalance": 1000
},
"position": {
"id": 637054,
"currency": "USD",
"symbol": "MCD",
"securityName": "Common Stock",
"units": 5,
"marketValue": 1403.55,
"currentPrice": 280.71,
"securityType": "Stock"
},
"asset": {
"currentBalance": 1000,
"twoMonthAverage": -1865.96,
"sixMonthAverage": -7616.01,
"beginningBalance": -17795.6
}
}
},
"assets": {
"type": "checking",
"availableBalance": 1000,
"currentBalance": 1000,
"twoMonthAverage": -1865.96,
"sixMonthAverage": -7616.01,
"beginningBalance": -17795.6
}
}
```
How to read a Balance Analytics PDF report:
[Balance_Analytics_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/Balance_Analytics_HTR.pdf) (3MB)
### Verifying Transaction Histories {#verifying-transaction-histories}
The [Transaction Consumer Reporting Agency (TACRA)](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/tacra/index.md) report provides details on up to 24 months of credit and debit transaction histories, without the account owner's information. You can also specify report constraints, such as which `accountIds` to include in the report, the `fromDate` and `toDate` for transaction filtering, and `includePending` parameters.
The following example shows a successful JSON response when requesting a TACRA report:
```json
{
"id": "1000075473",
"title": "Mastercard Open Banking Transactions Report",
"customerType": "testing",
"customerId": 1000018865,
"consumerId": "a925b07c9e028c680ad9c1d18d2e7199",
"consumerSsn": "6789",
"disputeStatement": "Invalid data present.",
"type": "transactions",
"status": "success",
"createdDate": 1594678007,
"endUser": {
"name": "ABC Apartments",
"address": "123 Main St",
"city": "Murray",
"state": "UT",
"zip": "84123",
"phone": "555-2106",
"email": "customerservice@example.com",
"url": "example.com"
},
"constraints": {
"accountIds": [
"1000075473"
],
"fromDate": 1578952809,
"toDate": 1594677609,
"includePending": true,
"reportCustomFields": [
{
"label": "loanID",
"value": "12345",
"shown": true
},
{
"label": "trackingID",
"value": "5555",
"shown": true
},
{
"label": "loanType",
"value": "car",
"shown": false
},
{
"label": "vendorID",
"value": "1613aa23",
"shown": true
},
{
"label": "vendorName",
"value": "PSC Finance",
"shown": false
}
],
"findTransaction": [
{
"findTransactionDescriptionMemo": "Payment to PSC Finance",
"findTransactionAmountFrom": -100.01,
"findTransactionAmountTo": 200,
"findTransactionCategory": [
"Payment",
"Transfer"
]
}
]
},
"startDate": 1579348800,
"endDate": 1594382400,
"days": 174,
"seasoned": false,
"portfolioId": "wqbh0r2kbv5g-4-port",
"institutions": [
{
"id": 102105,
"name": "FinBank Profiles - A",
"urlHomeApp": "http://www.bank.example.com",
"accounts": [
{
"id": 1000075473,
"number": "5015",
"name": "Super Checking",
"type": "checking",
"availableBalance": 1000,
"aggregationStatusCode": 0,
"balance": 1000,
"balanceDate": 1594676289,
"transactionsCount": 2,
"transactions": [
{
"id": 100001490719,
"amount": -99,
"postedDate": 1594382400,
"description": "ACH Withdrawal AMERICA FIRST CR",
"normalizedPayee": "America First Cr",
"institutionTransactionId": "0000000000",
"category": "Transfer",
"memo": "Payment to PSC Finance"
},
{
"id": 100001490897,
"amount": 199.7,
"postedDate": 1594123200,
"description": "Payment to PSC Finance",
"normalizedPayee": "T-Mobile",
"institutionTransactionId": "0000000000",
"category": "Payment",
"memo": "TMOBILE debit"
}
]
}
]
}
]
}
```
Sample TACRA PDF report:
[TACRA_Example_Report.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/TACRA_Example_Report.pdf) (2MB)
#### Alternative Flow {#alternative-flow}
Rather than having Data Connect auto-generate your report, you may prefer to generate the report creation at a later time. To do so, you can send the below request(s) for your customer:
**Verification of Income (VOI):**
API Reference: `POST /decisioning/v2/customers/{customerId}/voi`
**Balance Analytics (BA):**
API Reference: `POST /decisioning/v2/customers/{customerId}/reports/balance-analytics/userTypes/{userType}`
**Transactions, CRA (TACRA):**
API Reference: `POST /decisioning/v2/customers/{customerId}/transactions`
We also recommend listening for report webhook events for this scenario as a notification will sent when report generation is finished (see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)).
Finally, use the [Get Report by Report ID](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md#get-report-by-report-id) endpoint to obtain the report when ready using the `reportId`.
## Summary of Services {#summary-of-services}
The table below summarizes the Open Finance services that are useful for common tenant screening scenarios.
| Data Connect Product Type | Report(s) Generated | Included Data and Analytics |
|--------------------------------------------------------------------------------------------|---------------------|----------------------------------------------------------------------------------------------------------------------------------|
| Verification of Income (VOI) | VOI | Deposit Income Streams, Account Ownership, Accounts Summary, Transaction History (up to 24 months) |
| Verification of Assets (VOA) | VOA | Assets Summary, Non-Sufficient Funds Summary, Account Ownership, Accounts Summary, Transaction History (up to 12 months) |
| Balance Analytics (BA) | Balance Analytics | Balance Analytics, Account Ownership, Transaction History (up to 24 months), Accounts Summary, Time Interval Type |
| Verification of Income \& Employment with Credentialed Payroll (VOIE-Credentialed Payroll) | VOIE - Payroll | Employment Summary, Income Summary |
| Verification of Assets \& Income (VOAI) | VOAI - Transactions | Deposit Income Streams, Non-Sufficient Funds Summary, Account Ownership, Accounts Summary, Transaction History (up to 24 months) |
| Transactions (TACRA) | Transaction CRA | Transaction History (up to 24 months) |
## More Integration Tips {#more-integration-tips}
### Report Refresh {#report-refresh}
Any report generation request for the same customer
after the initial report is considered a refresh and returns updated
data. A refresh is executed without re-engaging the customer via a
client-initiated API call.
To directly generate or refresh a report, use the report generation
endpoint specific to that report - see [Reports List](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/index.md).
The response includes the status of
the report generation and a report ID which can be used to track the
associated report webhooks and to get the report later. Refreshed
reports default to the same parameters as the original report, unless
specified otherwise.
### Order Reports Tool {#order-reports-tool}
Our no-code Order Reports tool enables you to send Data Connect emails directly to consumers and view the generated reports without completing a direct integration. See [the Order Reports documentation](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/order-reports/index.md) for details of how to access and use the tool.
### Test Profiles {#test-profiles}
Test the APIs by connecting data using our test institutions and test
accounts: see [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md).
Ensure the test profile you select contains account types that are
supported by the report you will be ordering.