GuidesRecipesAPI ReferenceChangelog
Log In
Guides

Getting Started

This page will help you get started with Income Verification via the Snappt Enterprise API

Income Verification

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.

Create an Income Verification Session

In order to create an Income Verification session, you follow the same steps in the Getting Started for Fraud Detection. Once a property has Income Verification active, then any Document Types that meet the criteria for Income Verification review will be processed after application submission.

Current uploaded documents must be classified as a PAYSTUB 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 they are for Fraud Detection. Once your documents have been reviewed for both Fraud and Income, then your report will be ready and the webhook will be delivered.

Obtaining a Report

In order 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.

If Income Verification is active for a property or an income calculation has been made for an applicant in the past, you will be able to view the Applicant's Income Verification report if the documents have met the above criteria.

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 added at the root level of the response body.

If the queryParam includeDocuments=true has been included, then the income calculation for each document will have an incomeVerificationDetails object with Income Verification information.

{
    "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": []
    }
}

Income Verification Warning and Error Cases

When there is an issue with an income calculation, a warning or error will be provided in the statusDetails array located on the incomeVerificationDetails object at the root level of the response.

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

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.

Updated 5 days ago