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. The incomeVerificationDetails object is always present at the root level of the response body. Its value tells you the outcome of income verification for the applicant (see Interpreting incomeVerificationDetails below).

If the query parameter includeDocuments=true has been included, then the response will also include a per-document incomeVerificationDetails object on every document. The per-document grossIncome is populated only when a calculation was produced; it is null when the calculation errored or no calculation ran.

{
    "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. Read the status field first; it tells you which outcome applies and whether the income figures are usable.

📘

The top-level result field reflects only fraud rulings and is independent of incomeVerificationDetails. A response can have result: "CLEAN" and a "rejected" or "error" income status at the same time.

🚧

Income figures are null on error. Previously, the numeric fields could still be populated on status: "error". They are now always null in that case (and on "rejected" / "pending"), so income figures are present only when the result is usable. Make sure your integration treats a null income value as "no income to act on" and tolerates the new "pending" and "rejected" status values.

Income Verification Warning and Error Cases

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

On "warning", the calculation completed and the income figures are populated; the codes flag caveats you may want to surface to a reviewer.

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

On "error", the income figures are null; the reason and the supporting context (consecutiveDays, dates, income source, applicant name) remain visible so you can see why the calculation was rejected.

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

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.

No Calculation Ran (pending / rejected)

When Snappt runs no income calculation for a submission, incomeVerificationDetails is still present, with null income figures and a status of "pending" or "rejected":

• "pending" means eligibility is still being determined. statusDetails is empty. Check again later.
• "rejected" means no calculation will be produced for this submission. A single 1000-series code in statusDetails tells you why.

Previously these cases returned incomeVerificationDetails: null with no reason. The 1000-series codes give you that reason directly, so you do not need to inspect documents[] to infer it.

1000-Series Codes (no calculation ran)

Example of a "rejected" response (no eligible income documents, code 1001):

{
  "incomeVerificationDetails": {
    "calculationDate": null,
    "grossDailyIncome": null,
    "grossMonthlyIncome": null,
    "grossYearlyIncome": null,
    "consecutiveDays": null,
    "status": "rejected",
    "statusDetails": [
      {
        "code": 1001
      }
    ]
  }
}

Example of a "pending" response (eligibility still being determined):

{
  "incomeVerificationDetails": {
    "calculationDate": null,
    "grossDailyIncome": null,
    "grossMonthlyIncome": null,
    "grossYearlyIncome": null,
    "consecutiveDays": null,
    "status": "pending",
    "statusDetails": []
  }
}

What to request from the renter

When you see a "rejected" status, the code points to the next step:

• 1001 / 1002 - The renter should resubmit original income PDFs downloaded directly from their payroll provider (rather than scans, screenshots, print-to-PDF exports, or renamed files), classified as one of the supported income document types.
• 1003 - The submission was not eligible; review the applicant's submission and re-run as needed.
• 1004 - Transient; retry the lookup later.

📘

incomeVerificationDetails: null (the object itself is null) is reserved for the case where there is no income-verification signal at all, most commonly when Income Verification is not enabled on the property. Enable it using the POST endpoint if income data is desired.

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.