Income Verification

Overview

Income Verification is an optional capability that runs alongside Fraud Detection. When enabled on a property, every income document submitted by an applicant is first checked for tampering by Fraud Detection. Documents that pass the fraud check are then passed to the income calculator, which computes gross daily, monthly, and yearly income across the submitted documents and surfaces any caveats or unverifiable conditions.

This guide covers how to enable Income Verification on a property, how to submit income documents, and how to interpret the income calculation that appears on the applicant response.

Enabling Income Verification

To start using the Income Verification flow with your Snappt properties, the feature needs to be enabled on the property using the POST /properties/{propertyId}/income-verification endpoint.

Submitting Income Documents

Income documents are submitted using the same flow as Fraud Detection (see Getting Started). Once a property has Income Verification active, any document classified as one of the supported types below will be processed for income verification after application submission.

Uploaded documents must be classified as one of the following income document types in order to be processed for income verification:

• PAYSTUB
• DEPARTMENT_OF_VETERANS_AFFAIRS_BENEFIT_LETTER
• SOCIAL_SECURITY_BENEFITS_LETTER
• SOCIAL_SECURITY_STATEMENT

Documents can be classified using the Document Upload Portal or via the Upload Document endpoint.

📘

Income Verification document criteria can be found here

Checking for the Report Ready Status

The steps for obtaining a REPORT_READY webhook are the same as for Fraud Detection. Once your documents have been reviewed for both Fraud and Income, your report will be ready and the webhook will be delivered.

Obtaining a Report

To obtain your PDF report for Income Verification, you will use the same GET /applicants/{applicantId}/report endpoint as you would for a Fraud Detection report.

The income calculation appears in the report when at least one submitted document was eligible (see Submitting Income Documents) and passed the fraud check. Otherwise, the report is generated as a Fraud Detection report without an income section.

How To Fetch Available Income Calculations

Once an Income Verification report has been created, an applicant's income can be viewed using the GET /applicants/{applicantId} endpoint. If an income calculation for an applicant is available, an incomeVerificationDetails object will be present at the root level of the response body.

If the query parameter includeDocuments=true has been included, then the response will also include a per-document incomeVerificationDetails object on every document that contributed to the calculation.

{
    "id": "7d54e8a7-ade7-41bb-afef-0ea0254586b7",
    "fullName": "Test User",
    "firstName": "Test",
    "middleInitial": null,
    "lastName": "User",
    "email": "[email protected]",
    "phone": null,
    "notification": false,
    "entryId": "2a1956f5-b319-4f95-a56f-c7af31f5bb40",
    "insertedAt": "2024-06-13T02:56:50.000Z",
    "updatedAt": "2024-06-13T02:56:50.000Z",
    "status": "READY",
    "result": "CLEAN",
    "applicantDetailId": "ae99c8a2-6ecf-4339-8872-fb9ff68ab9e7",
    "documents": [
        {
            "id": "3d22f8df-676f-4245-bc1c-075acd591f9f",
            "insertedAt": "2024-06-13T02:56:50.000Z",
            "type": "PAYSTUB",
            "result": "CLEAN",
            "incomeVerificationDetails": {
                "calculationStartDate": "2024-06-12T00:00:00.000Z",
                "calculationEndDate": "2024-07-19T00:00:00.000Z",
                "grossIncome": 1000,
                "incomeSource": "Snappt",
                "applicantName": "Test User"
            }
        }
    ],
    "incomeVerificationDetails": {
        "calculationDate": "2024-06-13T03:01:44.972Z",
        "grossDailyIncome": 26.32,
        "grossMonthlyIncome": 789.47,
        "grossYearlyIncome": 9605.26,
        "consecutiveDays": 38,
        "status": "ok",
        "statusDetails": []
    }
}

Interpreting incomeVerificationDetails

The incomeVerificationDetails object is always present in the response. Its value tells you which of five outcomes applies to this applicant:

When incomeVerificationDetails is null, the most common reasons are:

• documents[] contains entries. Income documents were submitted, but none were ruled CLEAN by our fraud system, so nothing reached the income calculator. The renter should resubmit original PDFs downloaded directly from their payroll provider or bank, rather than scans, screenshots, print-to-PDF exports, or renamed files.
• documents[] is empty. No income documents were submitted at all. The renter needs to submit income documents.
• Income Verification is not enabled on this property. No calculation was attempted. Enable Income Verification on the property using the POST endpoint if income verification is desired.

Branching on these outcomes is sufficient. You do not need to inspect document type values to predict whether incomeVerificationDetails will be populated. The response shape itself is the source of truth.

📘

The top-level result field reflects only fraud rulings and is independent of incomeVerificationDetails. A response can have result: "CLEAN" and incomeVerificationDetails: null at the same time.

Income Verification Warning and Error Cases

When status is "warning" or "error", one or more reason codes appear in statusDetails.

{
  "incomeVerificationDetails": {
    "calculationDate": "2024-06-13T03:01:44.972Z",
    "grossDailyIncome": 26.32,
    "grossMonthlyIncome": 789.47,
    "grossYearlyIncome": 9605.26,
    "consecutiveDays": 38,
    "status": "error",
    "statusDetails": [
      {
        "code": 3004
      }
    ]
  }
}

One detail worth calling out explicitly: the numeric fields (grossDailyIncome, grossMonthlyIncome, grossYearlyIncome) may still be populated when status is "error". For example, if the recipient name on the documents does not match the applicant (code 3003), the calculator can still compute the math but cannot reliably attribute the income to the applicant. Treat the numbers as informational only in that case and follow the handling guidance in the table above.

Income Verification Warning Codes with Report Verbiage

• 2000 - Gross pay is missing from one or more documents.
  • Income reported is based on documents that include Gross Pay totals only.
• 2003 - Applicant name may not match documents.
  • One or more names on documents within this submission may not match the applicant's name.
• 2006 - The pay start and/or end dates are missing from one or more documents.
  • We cannot verify the applicant's income, because the pay period start and/or end dates were not available on the documents provided.
• 2008 - Income Source is missing from one or more documents.
  • Documents do not contain income source details. View the results summary for more information.Documents do not contain income source details.
• 2009 - Paystub start date is older than 90 days for a paystub; other paystubs are still reviewable.
  • One or more documents within this submission are older than 90 days. All documents older than 90 days have been removed from the calculation.
• 2010 - Document excluded from calculation.
  • One or more documents have been removed from the calculation.
• 2011 - Duplicate document was submitted.
  • One or more duplicate documents were found and removed from the calculation.
• 2012 - Documents removed, not most recent consecutive paystubs.
  • One or more documents have been removed from the calculation due to not being the most recent consecutive set of paystubs.
• 2018 - Joint account, applicant name matches.
  • The connected account appears to be a joint account, at least one of the names on the account matches the applicant's name.
• 2019 - Non-recurring income detected.
  • One or more of the sources included in the gross income calculation may include non-recurring income.
• 2020 - Account may be a business account.
  • One or more documents within this submission may be from a business account.
• 2021 - Tax documents from a prior tax year.
  • One or more of the uploaded tax documents are from a prior tax year and may not reflect the applicant's current income. Please confirm that the most recent tax return has been provided.
• 2022 - Tax documents missing some required information.
  • One or more of the uploaded tax documents are missing some required information, which may impact the income calculation. Please review the documents to confirm they are complete.
• 2023 - Tax return filed as Married Filing Jointly.
  • The uploaded tax return was filed as Married Filing Jointly. The total income shown may include a spouse's earnings.

Income Verification Error Codes with Report Verbiage

• 3001 - Gross pay is missing from all documents.
  • We cannot verify the applicant's income, because the gross income was not available on the documents provided.
• 3002 - Recipient Name is missing from one or more documents.
  • Income data is unavailable because the name on the connected tax account does not match the applicant's name.
• 3003 - Recipient name does not match across all documents.
  • We cannot verify the applicant's income, because the recipient name on the documents provided does not match the applicant name on file.
• 3004 - Documents do not span a minimum of 28 consecutive days.
  • We cannot verify the applicant's income, because the documents provided did not include 28 days of consecutive pay.
• 3005 - Documents do not represent pay issued within the past 90 days.
  • We cannot verify the applicant's income, because the documents within this submission do not represent pay issued within the past 90 days.
• 3007 - The pay start and/or end dates are missing from all documents.
  • We cannot verify the applicant's income, because the pay period start and/or end dates were not available on the documents provided.
• 3008 - There are not 28 consecutive days WITHIN the last 90 days.
  • We cannot verify the applicant's income, because the documents representing pay issued within the past 90 days do not cover a minimum of 28 consecutive days.
• 3020 - Bank account may be a business account
  • We cannot verify the applicant's income because one or more documents within this submission may be from a business account.
• 3021 - Tax documents are from a prior tax year
  • We cannot verify the applicant's income because the uploaded tax documents are from a prior tax year and do not reflect the applicant's current income. Please request the most recent tax return.
• 3022 - Tax documents missing required information
  • We cannot verify the applicant's income because none of the uploaded tax documents contained the information needed to calculate income. Please request complete tax return documents.
• 3023 - Tax return filed as Married Filing Jointly
  • The uploaded tax return was filed as Married Filing Jointly, and we cannot determine the applicant's individual income. Please request separate income documentation, such as the applicant's W-2s, pay stubs, or other individual income documents.

Override / Audit Codes (4xxx)

The 4000-series codes are override / audit markers. They appear in statusDetails when a calculation has been manually overridden by a reviewer (4001-4004), or when a document-level condition was automatically overridden and the document was still included in the calculation (4005).

Unlike the 2xxx and 3xxx ranges, 4xxx codes are never treated as errors. They accompany a status of "ok" or "warning", and the calculated income values are populated and usable. Treat them as informational context about why a calculation was adjusted - not as a reason to withhold the numbers.

Override / Audit Codes with Report Verbiage

• 4001 - Additional income sources were provided during review.
• 4002 - Non-recurring income was included in the calculation.
• 4003 - An offer letter was provided and accepted as proof of income.
• 4004 - The calculated income figure was manually corrected.
  • Codes 4001-4004 share a single message on the report: "The gross income calculation was updated using data from the applicant's uploaded documents or connected accounts."
• 4005 - A name mismatch on a document was overridden, and the document was included in the calculation.
  • When the document is the selected income source and passed the fraud check (CLEAN): "A name mismatch on this document was overridden and included in the income calculation."
  • When the document did not contribute to the selected calculation: "A name mismatch was noted on this document."
  • Note: if the document's fraud result is UNDETERMINED, EDITED, or PENDING, the override message is not shown - the document displays the standard message for that fraud result instead.