Cash Atlas V1 API Reference

API Reference Overview

Introduction

This document provides information on how to interact with the Nova Credit API to obtain a Cash Atlas report.

The best way to get the Cash Atlas report using Nova Credit's API is to have your applicants use NovaConnect, an easy-to-use and secure JavaScript module. Visit our Quickstart Guide for all details on how to get Nova Credit API credentials and integrate NovaConnect into your app or website today.

Framework and Protocol

The Nova Credit API is organized around REST. It uses resource-oriented URLs, HTTP response codes, and native HTTP functionality such as authentication and verbs. Note that our APIs are served over HTTPS; HTTP is not supported in production.

Delivery Formats

JSON is the default response format.

Endpoints

Our API host is api.novacredit.com. (See Quickstart Guide for environment information.)

Our resource URL patterns are:

Value	Description
/connect/accesstoken	Retrieves an access token for an applicant's Cash Atlas report
/connect/cash-atlas/v1/json	Retrieves an applicant's Cash Atlas report in JSON form
/connect/cash-atlas/v1/files/<filepath>	Retrieves a file associated with an applicant's Cash Atlas report. File endpoint is a draft and is subject to change.
/connect/status	Retrieves the status of an applicant's Cash Atlas report

Visit our Quickstart Guide to see details on how to call these endpoints with examples.

Data Types & Formats

Data Types

Type	Description
String	Extended character set, numbers and punctuation symbols. This includes non-ASCII language-specific characters such as ß, à, ç, é, and more (all encoded as utf8).
Integer	A rounded numerical value.
Float	A 64-bit floating decimal point format.
Bool	A boolean-flag indicating true or false.
Object	Nested JSON level with more field-values.
Array	A value or type array contains a zero or positive amount of elements. The elements can be of any type.

Data Formats

Format	Description
Timestamp	(String) UTC ISO 8601 data and time format. Full specs according to RFC 3339. Example: 1982-09-26T32:20:50.52Z
Full Date	(String) UTC ISO 8601 date format. Full date format in YYYY-MM-DD. Example: 1982-09-26
Short Date	(String) UTC ISO 8601 date format. Shorter format in YYYY-MM. Example: 1982-09
UUID	(String) Universally Unique Identifier according to RFC 4122
URI	(String) Uniform Resource Identifier according to RFC 3986
Full Version	(String) Semantic versioning. http://semver.org/
Confidence Score	(Integer) A number from 0 to 100 -- the higher the score, the greater Nova Credit's confidence in the corresponding value is

Webhooks

Webhooks are the mechanism that Nova Credit uses to inform you of core initialization and completion steps for each widget interaction. One session can consist of multiple suppliers. Only one terminal status outcome is sent per widget open; other supplier-flow outcomes are recorded and attached to the webhook body in the history node.

We make a POST API call to the webhook callback URL that you provide. Webhooks can be managed in the Developer tab on the Nova Credit Dashboard, where you must set your callback URL and can toggle your various event subscriptions on and off. Some events or statuses are subscribed to by default.

Webhook Event Types

Each Webhook API call will contain one of the event types listed below in the JSON body:

Event Type	Description
VISIT	A single NovaConnect widget interaction, which can consist of multiple suppliers. Only one terminal status outcome is sent per widget open; other supplier-flow outcomes are recorded and attached to the webhook in the history node
REGENERATED_VISIT	Only occurs for reports that have been regenerated. This event type also includes a novaReportRevision in the webhook body.

Webhook Status Codes

Each Webhook API call will contain one of the status codes listed below:

Status	Description	Terminal Status?
PENDING	A visit has been initialized upon opening the NovaConnect widget, or a given supplier has been chosen	✗
SUCCESS	The data source has successfully provided information on the applicant	✓
EXPIRED	The visit has expired before the applicant was able to complete the flow. This will be sent if no completion 72 hours after initial widget opened	✓
ERROR	An error occurred and the Cash Atlas Report could not be compiled. If there isn't a detailed substatus, send a message to your Nova Credit Representative with the publicToken	✓
SKIPPED	The applicant opted not to finish the visit or supplier. This can be caused by exiting from the Cash Atlas widget or clicking a button to skip (for example, clicking "I cannot complete this step")	✓
BUREAU_UNRESPONSIVE	The applicant has encountered a data supplier outage while going through the widget. They may need to go through NovaConnect again at a later time	✓
NOT_AUTHENTICATED	The applicant was unable to verify their identity	✓
NON_CONTRIBUTING_APPLICANT	The applicant selected to not contribute income	✓

Webhook Body

Webhook Body Key	Description
eventType	Event Type (see event type table above) corresponding to this webhook
status	Status (see status code table above) corresponding to this webhook
substatus	A more detailed status. See substatus types
publicToken	Unique UUID associated with this status, which can be used to retrieve the Nova Credit report
externalId	Optional unique identifier passed in by the Nova Credit customer (you) with this application. This key will only be present if externalId was passed in
userArgs	Optional string passed in by the Nova Credit customer (you) with this application. This key will only be present if userArgs was passed in
eventId	Unique ID for the webhook
eventCreatedTime	Webhook event timestamp
novaReportRevision	Only included for webhooks with the REGENERATED_VISIT event type. Refers to the revision number of the report
history	An array containing 1 or more objects, containing data on all of the statuses an applicant has reached within one Cash Atlas widget instance, sorted by most recent to least recent
history.eventType	Each history object will have a SUPPLIER event type
history.companyCode	Data supplier for this history object
history.dateAttempted	Timestamp marking when this corresponding history object was begun
history.status	Status (see status code table above) corresponding to this history object
history.substatus	A more detailed status. See substatus types

Note that the status will be informed by the most recent supplier event status.

Example:

{
    eventType: 'VISIT',
    status: 'SUCCESS',
    publicToken: '6b986690-458b-11e7-98fb-a71570ea65a6',
    externalId: '25ad7063-fe76-437a-b4d8-3662ba4cc9c7',
    userArgs: '235234224',
    eventId: '028d9354-3991-46c4-97df-bd6c2ff09733',
    eventCreatedTime: '2019-09-26T33:15:23.17Z',
    history: [
        {
            eventType: 'SUPPLIER',
            status: 'SUCCESS',
            substatus: 'ACCOUNT_TOO_NEW',
            companyCode: 'USA_FIN',
            dateAttempted: '2019-09-26T19:20:00.00Z' // newest timestamp
        },
        {
            eventType: 'SUPPLIER',
            status: 'PENDING',
            companyCode: 'USA_FIN',
            dateAttempted: '2019-09-26T19:18:00.00Z' // oldest timestamp
        }
    ]
}

Webhook Signature

Nova Credit optionally signs webhook payloads in order to allow for trust verification of inbound webhook requests. When configured, the webhook request will contain these additional headers:

Header	Value
X-Timestamp	timestamp of request generation
X-Nova-Signature	SHA256 HMAC digest of request timestamp and payload, period-delimited. Your Webhook Signatures Secret Key is found under the Webhooks section on the Developer tab of your Nova Credit Dashboard.

Please contact your Nova Credit account manager to enable this feature.

Example verification of signature:

const crypto = require('crypto');

const signature = req.get('X-Nova-Signature');
const timestamp = req.get('X-Timestamp');

const checkPayload = `${timestamp}.${JSON.stringify(req.body)}`;
const checkDigest = crypto.createHmac('sha256', '< webhook secret key >')
    .update(checkPayload)
    .digest('base64');

return crypto.timingSafeEquals(signature, checkDigest);

Sandbox Mode

Finicity

To access a Cash Atlas sandbox report, you must pass certain identifying consumer information into the Cash Atlas widget. This information may be passed in directly via prefill keys. Please refer to the Quickstart Guide to learn more about prefill keys.

Along with the identifying consumer information that is collected, the user may connect their bank account through our partner, Finicity, Inc. Finicity provides a set of usernames and password combinations for testing purposes that can be found in the Finicity documentation. For example, selecting FinBank and using a username/password of demo/go will allow you to connect test accounts.

The following Nova Credit test user reports have been created and can be accessed by inputting the following information:

Inputs	Default User	Single Primary Account User	Multi-Account User	Joint Account User	Debt Account Linked User	No Income User
First name	Raymond	Sarah	Mike	Jason	Derek	Nolan
Last name	Marshal	Single	Many	Joint	Debt	NoTransactions
Date of birth	1995-10-01	1986-10-12	1992-05-08	1976-03-09	1984-04-12	1992-03-07
Email address	raymond@email.com	sarah@email.com	mike@email.com	jason@email.com	derek@email.com	nolan@email.com
Phone	310-555-6789	415-231-5348	917-340-3249	208-351-0093	512-213-3322	217-277-6633
Address	456 7th Street	6100 Evergreen Way	915 Snover Street	2213 W Montrose Avenue	1105 Bowie Rd	6300 N Illinois St
City	Modesto	Everett	Houston	Chicago	Austin	Fairview Heights
State	CA	WA	TX	IL	TX	IL
Zip	95313	98203	77007	60618	78773	62208
Stated employer	Raymond's Designs	Boeing	Target	Microsoft	Charles Schwab	Optional
Stated annual income	12000	120000	73000	110000	135000	Optional

These users will return a SUCCESS status in the webhook. The "No Income User" will return with a NO_RECENT_USABLE_INFORMATION substatus.

Refer to the Finicity documentation to view alternative user ID and password combinations to trigger different Finicity states.

If testing multiple aggregators in sandbox mode, you will need to select a bank first. Please select FinBank to connect with Finicity.

Simulating Different Cases in Sandbox

Enter the following inputs as the "Last Name" of the applicant in prefills to simulate a different case.

Inputs	Description
expiresoon	Simulates the EXPIRED status, immediatey instead of waiting 72 hours
supplierdown	Simulates the BUREAU_UNRESPONSIVE status

Akoya

Users may also connect their bank accounts through our partner Akoya to access a Cash Atlas sandbox report. Upon loading the widget, select the test user displayed, and the appropriate report will be fetched. The test users mirror those above for Finicity.

If testing multiple aggregators in sandbox mode, you will need to select a bank first. Please select Mikomo to connect with Akoya.

Paystub Verification

For testing purposes on the paystub page of the Cash Atlas widget, we have provided a set of filename combinations that correspond with different outcomes. These are as follows:

Filename	Paystub Outcome	Detect Outcome
emelia	SUCCESS (default paystub)	Not Detected
emelia_detected	SUCCESS (default paystub)	Detected
emelia_timeout	SUCCESS (default paystub)	Timeout
emelia_error	SUCCESS (default paystub)	Error
empty	NOT_AUTHENTICATED (empty paystub)	Error
marie	SUCCESS (thin file paystub)	Not Detected
larry	SUCCESS (low income paystub)	Not Detected
down	BUREAU_UNRESPONSIVE	N/A
missingfields	SUCCESS (paystub which is missing fields)	Not Detected
Any other filename	NOT_AUTHENTICATED	Error

In addition to these filename combinations, we have provided inputs to trigger fraud outcomes in the irregularity detection response.

Fraud v2 Sandbox

These inputs should be passed in directly using prefill values, and can be used in combination with the emelia filename above. Please refer to the Quickstart Guide to learn more about prefill keys.

These prefill values will only work if fraud v2 is enabled for your account in addition to irregularity detection. See irregularity_detection

For each outcome below, use a Prefill First Name of getAdaptiveDecisionResult

Prefill Last Name	Irregularity Detection Status	Fraud Indication Verdict
error	N/A	N/A
pdfTrusted	Not Detected	Trusted
pdfHighRisk	Detected	High Risk
pdfWarningDigitalPrint	Not Detected	Warning
pdfWarningApproved	Review	Warning
pdfNormalNoDigitalModification	Not Detected	Normal
pdfNormalApproved	Review	Normal
pdfNormalManualReview	Review	Normal
imageTrusted	Not Detected	Trusted
imageHighRiskApproved	Detected	High Risk
imageHighRiskManualReview	Detected	High Risk
imageWarningApproved	Not Detected	Warning
imageWarningManualReview	Detected	Warning
imageNormalNoDigitalModification	Not Detected	Normal
imageNormalOther	Review	Normal

Fraud v3 Sandbox

These inputs should be passed in directly using prefill values, and can be used in combination with the filenames above. Using the emelia_detected filename will always result in an outcome of DETECTED.

For each outcome below, use a Prefill First Name of getAdaptiveDecisionResult.

Prefill Last Name	File Type	Irregularity Detection Status
pdfTrusted	pdf	NOT_DETECTED
pdfHighRisk	pdf	DETECTED
pdfWarningApproved	pdf	REVIEW
imageTrusted	image	NOT_DETECTED
imageHighRiskManualReview	image	DETECTED

USA_ATOMIC

Sandbox Testing

We provide multiple sandbox users for testing: Jane, Alice and Paddy.

To access the reports please pass the first names via prefill keys and then choose Test User on the Atomic Simulator page. If you do not enter a name for any of the sandbox users, we will default to the "Jane" report.

Here is some information about each sandbox report.

Report Info	Jane (Default)	Alice	Paddy	Jimmy	Patricia
Employment Status	active	terminated	active	active	active
Employment Type	fulltime	fulltime	fulltime	fulltime	fulltime
Annual Income	60000	21612	156013.2	130000	52000
Pay Frequency	monthly	semimonthly	semimonthly	biweekly	weekly

Widget Testing

If you are using the sandbox, you will see a special Atomic Simulator page instead of the Atomic Widget. This page contains multiple options for testing different widget states. You can test success flows, cascade and various Atomic failure states.

If you are performing production testing, then you can use the Atomic Widget to trigger different testing scenarios. Here is a list of different test cases. The test cases should work for any source provider as long as you enter the name and phone number as specified for each test case.

Report Structure

Example of the JSON structure of the Cash Atlas report response:
{
  "meta": {
    ...
  },
  "product": {
    ...
  },
  "sources": [
    ...
  ],
  "identities": [
    ...
  ],
  "employment": [
    ...
  ],
  "bank_transactions": [
    ...
  ],
  "expenses": [
    ...
  ],
  "income": {
    ...
  },
  "metrics": [
    ...
  ],
  "attributes": [
    ...
  ],
  "adverse_action_codes": [
    ...
  ]
}

The Cash Atlas report response structure is as follows:

• meta {object}
• product {object}
• sources {array}
• identities {array}
• employment {array}
• bank_transactions {array}
• expenses {array}
• income {object}
• metrics {array}
• attributes {array}
• adverse_action_codes {array}

Report Body

meta {}

Example snippet of meta in the report response:

{
  "meta": {
    "public_token": "ff0886a4-f3ff-11e6-bc64-92361f002671",
    "user_args": "235234224",
    "created_at": "2017-01-13T11:07:46.51Z",
    "api_version": "4.6.85",
    "nova_report_revision": "1",
    "external_id": "d167c6bb-225c-461c-be63-f0bc3a1f62ea"
  },
  ...
}

Information specific to the report that's been returned.

Field	Format	Notes
public_token	UUID	The unique identifier of this report
user_args	String	The input of the userArgs function in NovaConnect
created_at	Timestamp	The date the credit report was retrieved
api_version	Full version	The API version used to generate this report
external_id	String	The unique applicant identifier of the report from your system. Can be null if it is not provided.
nova_report_revision	String	The revision name for this report. This field will be null if this report has never been revised.

product {}

Example snippet of product in the report response:

{
  "product": {
    "name": "Village Communities",
    "product_id": "9cf178e0-760e-11e7-abf3-5da9d338ae4b",
    "inquiry_type": "TENANT"
  },
  ...
}

Details of the product the applicant applied for. Please refer to the Client-Side Integration section in the Quickstart Guide.

Field	Format	Notes
name	String	Product name
product_id	UUID
inquiry_type	String	See product inquiry_type values

sources []

Example snippet of sources in the report response:

{
  "sources": [{
    "source_id": "USA_FIN",
    "source_type": "BANK",
    "status": "SUCCESS"
  }],
  ...
}

A list of data sources used to build the applicant's report.

Field	Format	Notes
source_id	String	A human-readable identifier for the source, unique within the context of the report
source_type	String	See source_types
status	String	The final status for the source. See status

identities []

Example snippet of identities in the response:

{
  "identities": [{
    "source_id": "CONSUMER_INPUT",
    "first_name": "Raymond",
    "last_name": "Marshal",
    "emails": ["raymond@email.com"]
  }],
  ...
}

The applicant's personal identity information reported from each data source.

Field	Format	Notes
source_id	String	The identifier for the source that reported the identity information. See sources
source_record_id	UUID	The identifier for an individual record within a source
first_name	String
last_name	String
full_name	String
middle_name	String
other_names	Array of String	A list of other names associated with applicant, such as aliases, maiden names, and other surnames
emails	Array of String
telephones	Array of String
matching	Object	See matching

matching {}

Example identities matching field object for case where there is a full name match:

{
  "matching": {
    "full_name": {
      "matched_sources": [
        {
          "source_id": "OCROLUS",
          "source_record_id": "5f19d40f-3c19-4a7d-ad7b-cc28dac40c4d"
        }
      ],
      "unmatched_sources": []
    }
  }
}

Example identities matching field object for case where there is no full name match:

{
  "matching": {
    "full_name": {
      "matched_sources": [],
      "unmatched_sources": [
        {
          "source_id": "OCROLUS",
          "source_record_id": "c31bf8c7-c25b-4d2c-a4bc-61f79fd46e65"
        }
      ]
    }
  }
}

Information about sources which have matching and conflicting values to a particular identity.

matching is returned in an object broken out by field, only certain fields are matched between sources. If only one identity item exists, there will be no matching field. Information about matching sources is stored wrapped in the MatchingField format, which indicates where each value was sourced from.

Field	Format	Notes
full_name	Object	Matched and unmatched sources for the full name of the applicant

MatchingField {}

Example matching field object for case where there is a field match:

{
  "matched_sources": [
    {
      "source_id": "OCROLUS",
      "source_record_id": "5f19d40f-3c19-4a7d-ad7b-cc28dac40c4d"
    }
  ],
  "unmatched_sources": []
}

Example matching field object for case where there is no field match:

{
  "matched_sources": [],
  "unmatched_sources": [
    {
      "source_id": "OCROLUS",
      "source_record_id": "c31bf8c7-c25b-4d2c-a4bc-61f79fd46e65"
    }
  ]
}

An object containing information about which sources have a matching value for a field and which sources contain conflicting values for the same field. A source is an object containing a source_id and a source_record_id if there are multiple source records.

Field	Format	Notes
matched_sources	Array	List of sources which have a value that matches this identity. See sources
unmatched_sources	Array	A list of sources which have a value that conflicts with this identity. See sources

employment []

Example snippet of employment in the report response:
{
  "employment": [
    {
      "source_id": "OCROLUS",
      "employer_name": "Microsoft",
      "employer_address_line_1": "1 Microsoft Way",
      "employer_address_line_2": null,
      "employer_city": "Redmond",
      "employer_state": "Washington",
      "employment_type": "fulltime",
      "employment_status":"active"
      "job_title": "Product Manager",
      "hire_date": "2017-04-19",
      "estimated_hire_date": null,
      "matching": {
        "employer_name": {
          "matched_sources": [
            {
              "source_id": "OCROLUS",
              "source_record_id": "edba0b20-22e5-11eb-916b-452b88954927"
            }
          ],
          "unmatched_sources": []
        }
      }
    }
  ]
}

Employment information specific to the applicant whose report is being accessed.

Field	Format	Notes
source_id	String	The identifier for the source that reported the employment information. See sources
source_record_id	UUID	The identifier for an individual record within a source
employer_name	String	Name of the applicant's employer
employer_address_line_1	String	Address line 1 where the applicant's employer is located
employer_address_line_2	String	Address line 2 where the applicant's employer is located
employer_city	String	City where the applicant's employer is located
employer_state	String	State where the applicant's employer is located
employment_type	String	Type of employment (contract, parttime or fulltime)
employment_status	String	Status of the applicant's employment (active or terminated)
job_title	String	Title of the applicant's job
hire_date	Full Date	Employee hire date as stated on the employment source
estimated_hire_date	Full Date	An estimate of the employee hire date. Only has a non-null value when hire_date is null
matching	Object	See matching

matching {}

Example employment matching field object for case where there is an employer name match:
{
  "matching": {
    "employer_name": {
      "matched_sources": [
        {
          "source_id": "OCROLUS",
          "source_record_id": "5f19d40f-3c19-4a7d-ad7b-cc28dac40c4d"
        }
      ],
      "unmatched_sources": []
    }
  }
}
Example employment matching field object for case where there is no employer name match:
{
  "matching": {
    "employer_name": {
      "matched_sources": [],
      "unmatched_sources": [
        {
          "source_id": "OCROLUS",
          "source_record_id": "c31bf8c7-c25b-4d2c-a4bc-61f79fd46e65"
        }
      ]
    }
  }
}

Information about sources which have matching and conflicting values to a particular employment.

matching is returned in an object broken out by field, only certain fields are matched between sources. If only one employment item exists, there will be no matching field. Information about matching sources is stored wrapped in the MatchingField format, which indicates where each value was sourced from.

Field	Format	Notes
employer_name	Object	Matched and unmatched sources for an employer name

MatchingField {}

Example matching field object for case where there is a field match:
{
  "matched_sources": [
    {
      "source_id": "OCROLUS",
      "source_record_id": "5f19d40f-3c19-4a7d-ad7b-cc28dac40c4d"
    }
  ],
  "unmatched_sources": []
}
Example matching field object for case where there is no field match:
{
  "matched_sources": [],
  "unmatched_sources": [
    {
      "source_id": "OCROLUS",
      "source_record_id": "c31bf8c7-c25b-4d2c-a4bc-61f79fd46e65"
    }
  ]
}

An object containing information about which sources have a matching value for a field and which sources contain conflicting values for the same field. A source is an object containing a source_id and a source_record_id if there are multiple source records.

Field	Format	Notes
matched_sources	Array	List of sources which have a value that matches this employer. See sources
unmatched_sources	Array	A list of sources which have a value that conflicts with this employer. See sources

bank_transactions []

Example snippet of bank_transactions in the report response:

{
  "bank_transactions": [
    {
      "source_id": "USA_FIN",
      "summary": {
        ...
      },
      "account_details": [
        ...
      ],
      "inflows": {
        ...
      }
    }
    ...
  ]
  ...
}

A list of data sourced from bank transactions. Each separate entry in the bank transactions list represents the set of data returned from a single source.

Field	Format	Notes
source_id	String	The identifier for the source that reported the bank transaction information. See sources
summary	Object	See summary
account_details	Object	See account_details
inflows	Object	See inflows

summary {}

Example snippet of summary within bank_transactions:

{
  "bank_transactions": [{
    "summary": {
      "months_available": 6,
    }
  }],
}

Summary information specific to the applicant whose report is being accessed. Available if an applicant connects their bank account.

Field	Format	Notes
months_available	Integer	Number of months of transaction data available on the report

account_details []

Example account detail field object:

{
  "bank_transactions": [{
    "account_details": [{
      "account_id": "36139831-0a91-4d1f-bc3e-edc908a978c6",
      "owner_full_name": "John Doe",
      "institution_name": "CHASE",
      "account_name": "INVESTMENT ACCOUNT",
      "account_type": "INVESTMENT",
      "date_opened": "2015-05-01",
      "oldest_transaction_date": "2015-05-03",
      "truncated_account_number": "1234",
      "responsibility": "INDIVIDUAL",
      "last_statement_end_date": "2015-05-30",
      "addresses": [
        {
          "address_id": "80421b7e-7918-4963-b5fb-85055c2994b7",
          "address": "225 Valencia St.",
          "street": "Valencia St.",
          "city": "San Francisco",
          "zipcode": "94103",
          "state": "CA"
        }
      ],
      "current_balance": 23422,
      "routing_number": "123445",
      "full_account_number": "789682736",
      "attributes": [
        {
          "name": "EXPENSES_COUNT_3_MONTH_AVG",
          "description": "Average count of expenses over the last 3 months",
          "node": "EXPENSES",
          "source_ids": ["USA_FIN"],
          "adverse_action_code": "66",
          "value": 10
        },
        {
          "name": "EXPENSES_COUNT_0_50_3_MONTH_AVG",
          "description": "Average count of expenses between $0 and $50 over the last 3 months",
          "node": "EXPENSES",
          "source_ids": ["USA_FIN"],
          "adverse_action_code": "67",
          "value": 9996
        },
        ...
      ],
    },
    ...
    ],
  }],
}

An array with each instance containing details about an account. The array can have zero objects, and there is no upper bound.

Field	Format	Notes
account_id	UUID	Unique identifier for the account
owner_full_name	String	Full name of the owner of the account
institution_name	String	Name of institution such as Chase or Bank of America
account_name	String	Name of the account within the bank
account_type	String	Type of the account within the bank. See account types
date_opened	Full Date	Date the account was opened
oldest_transaction_date	Full Date	Date of the oldest transaction for the account
truncated_account_number	String	If available, the last four digits of the account number
responsibility	String	See responsibility
last_statement_end_date	Full Date	End date of the of the most recent statement
addresses	Array	See addresses
current_balance	Float	Current balance of the account
routing_number	String	Routing number of financial institution for the account. Please contact your Nova Credit account representative to enable this field
full_account_number	String	The full account number for initiating ACH transfers for this account. Please contact your Nova Credit account representative to enable this field
attributes	Array	Attributes associated with this account. See attributes

addresses []

Example addresses field array:

{
  "addresses": [{
    "address_id": "80421b7e-7918-4963-b5fb-85055c2994b7",
    "address": "225 Valencia St., San Francisco, CA 94103",
    "street": "Valencia St.",
    "city": "San Francisco",
    "zipcode": "94103",
    "state": "CA"
  }],
},

Addresses is a history of contact information attached to this account. Addresses are returned in an array, can have zero objects, and there is no upper bound.

Field	Format	Notes
address_id	UUID	Unique identifier for the address
address	String	The full mailing address of the account owner
street	String	The street address where the account owner is located
neighborhood	String	The neighborhood where the account owner is located
district	String	The district where the account owner is located
city	String	The city where the account owner is located
zipcode	String	The zip code where the account owner is located
state	String	The state where the account owner is located

inflows {}

Example inflows field object:

{
  "bank_transactions": [{
    "inflows": {
      "total_annual": 24000,
      "total_adjusted_annual": 27600,
      "history": [
        {
          "year": 2019,
          "total": [ null, 2000, ... ],
          "misc_deposits": [ null, 100, ... ]
        },
        ...
      ],
    },
  }],
}

An object containing details about an account. Not included in reports when source_id is PLAID.

Field	Format	Notes
total_annual	Integer	Regular deposit streams, aggregated over the last 12 months
total_adjusted_annual	Integer	Regular deposit streams, aggregated over the last 12 months, scaled up using net-to-gross tax adjustment
history	Array	See history

history []

Example inflow history field object:

{
  "history": [{
    "year": 2019,
    "total": [ null, 2000, ... ],
    "misc_deposits": [ null, 100, ... ]
  }]
}

An array with each element containing information about the value of the inflow history.

history is returned in an array of objects (one object per year, from most recent to least). There are multiple histories that the history node reports and are denoted by separate keys in each history object. History arrays will be segmented by month. The first element is the month of December and the last is January. If no data is available for a given month the value will be null.

Field	Format	Notes
year	Integer	The given history's year
total	Array	All inflow streams to deposit accounts
misc_deposits	Array	Net miscellaneous deposits into accounts

expenses []

Example snippet of expenses in the report response:

{
    "expenses": [
        {
            "history": [
                ...
            ]
        }
    ]
}

An array containing details about the applicant's expenses.

Field	Format	Notes
history	Array	See history

history []

Example expenses history field object:

{
    "history": [{
        "year": 2021,
        "count": [
            ...
        ],
        "count_0_50": [
            ...
        ],
        "count_50_100": [
            ...
        ],
        "count_100_250": [
            ...
        ],
        "count_250_500": [
            ...
        ],
        "count_500_1000": [
            ...
        ],
        "count_above_1000": [
            ...
        ],
        "sum": [
            ...
        ],
        "sum_0_50": [
            ...
        ],
        "sum_50_100": [
            ...
        ],
        "sum_100_250": [
            ...
        ],
        "sum_250_500": [
            ...
        ],
        "sum_500_1000": [
            ...
        ],
        "sum_above_1000": [
            ...
        ]
    }]
}

An array with each element containing information about the expense history.

history is returned in an array of objects (one object per year, from most recent to least). There are multiple histories that the history node reports and are denoted by separate keys in each history object. History arrays will be segmented by month. The first element is the month of December and the last is January. If no data is available for a given month the value will be null.

For each range, the lower bound is exclusive, and the upper bound is inclusive. For example:

• The value $49.99 would fall into the range 0_50

• The value$50.00 would also fall into the range 0_50

• The value$50.01 would fall into the range 50_100

Field	Format	Notes
year	Integer	The history's given year
count	Array	Count of expenses over a 1 month period
count_0_50	Array	Count of expenses identified as being less than or equal to $50 over a 1 month period
count_50_100	Array	Count of expenses identified as being greater than $50 & less than or equal to $100 over a 1 month period
count_100_250	Array	Count of expenses identified as being greater than $100 & less than or equal to $250 over a 1 month period
count_250_500	Array	Count of expenses identified as being greater than $250 & less than or equal to $500 over a 1 month period
count_500_1000	Array	Count of expenses identified as being greater than $500 & less than or equal to $1000 over a 1 month period
count_above_1000	Array	Count of expenses identified as being above $1000 over a 1 month period
sum	Array	Sum of expenses over a 1 month period
sum_0_50	Array	Sum of expenses identified as being less than or equal to $50 over a 1 month period
sum_50_100	Array	Sum of expenses identified as being greater than $50 & less tha or equal to $100 over a 1 month period
sum_100_250	Array	Sum of expenses identified as being greater than $100 & less than or equal to $250 over a 1 month period
sum_250_500	Array	Sum of expenses identified as being greater than $250 & less than or equal to $500 over a 1 month period
sum_500_1000	Array	Sum of expenses identified as being greater than $500 & less than or equal to $1000 over a 1 month period
sum_above_1000	Array	Sum of expenses identified as being above $1000 over a 1 month period

income {}

Example snippet of incomes in the report response:

{
  "income": {
    "financial_accounts": [
      ...
    ],
    "paystubs": [
      ...
    ],
    "payroll": [
      ...
    ]
  }
}

Income information specific to the applicant whose report is being accessed. Not included in reports if income information is not found.

Field	Format	Notes
financial_accounts	Array	See financial accounts
paystubs	Array	See paystubs
payroll	Array	See payroll

financial_accounts []

Example snippet of financial_accounts:

{
  "income": {
    "financial_accounts": [
      {
        "source_ids": ["USA_FIN"],
        "model_version": "0.1.5",
        "model_type": "NOVA_INCOME",
        "descriptions": ["GUSTO PAY", "NAPOLI PIZZERIA DIR DEP"],
        "is_consistent": true,
        "net_recent": 20000,
        "gross_recent": 24000,
        "confidence_score_recent": 90,
        "net_annual": 20000,
        "gross_annual": 24000,
        "confidence_score_annual": 90,
        "matched_income": {
          "stated_employer": "Napoli Pizzeria",
          "stated_annual_income": 18000,
          "description": "NAPOLI PIZZERIA USA 6787 836XNLNKSEYCQ8B -",
          "net_income": 15480,
          "gross_income": 18923,
          "confidence_score": 80,
        },
        "history": [
          {
            "year": 2019,
            "gross": [ 2500, 5000, ... ],
            "net": [ 2250, 4500, ... ],
            "confidence_score": [90, 90, ...],
          },
        ]
      },
    ]
  }
}

Income information derived from financial account data.

Field	Format	Notes
source_ids	Array	The identifiers for the sources that reported the income information. See sources
model_version	String	The identifier for the income model version
model_type	String	See model types
descriptions	Array	Descriptions of active inflow streams, ordered by size of inflow stream over the past 3 months (max 3 inflow stream descriptions)
is_consistent	Boolean	Income has been received for the last 3 complete months
net_recent	Integer	Net (take home) income over the past three complete calendar months annualized
gross_recent	Integer	Gross income over the past three complete calendar months annualized
confidence_score_recent	Confidence Score	Confidence score for income over past three complete calendar months
net_annual	Integer	Net (take home) income over the past twelve complete calendar months
gross_annual	Integer	Gross income over the past twelve complete calendar months
confidence_score_annual	Confidence Score	Confidence score for income over past twelve complete calendar months
matched_income	Object	See matched_income
history	Array	See history

matched_income {}

Example matched income object:

{
  "matched_income": {
    "stated_employer": "Napoli Pizzeria",
    "stated_annual_income": 18000,
    "description": "NAPOLI PIZZERIA USA 6787 836XNLNKSEYCQ8B -",
    "net_income": 15480,
    "gross_income": 18923,
    "confidence_score": 80,
  }
}

An object that describes the income stream that best matches the stated employer name provided by the applicant. If no income stream matches, this object will be empty.

Field	Format	Notes
stated_employer	String	Stated employer name provided by the applicant
stated_annual_income	Integer	Stated annual income provided by the applicant
description	String	Description for the matched income stream
net_income	Integer	Net income for the matched income stream
gross_income	Integer	Gross income for the matched income stream
confidence_score	Confidence Score	Confidence score for the matched income stream. This is an indicator of how confidently this matched income represents true income

history []

Example income history field object:

{
  "history": [{
    "year": 2019,
    "gross": [ 2500, 5000, ... ],
    "net": [ 2250, 4500, ... ],
    "confidence_score": [90, 90, ...],
  }],
},

An array with each element containing information about the value of the income history.

history is returned in an array of objects (one object per year, from most recent to least). There are multiple histories that the history node reports and are denoted by separate keys in each history object. History arrays will be segmented by month. The first element is the month of December and the last is January. If no data is available for a given month the value will be null

Field	Format	Notes
year	Integer	The history's given year
gross	Array	Sums of gross income over 1-month periods. Current month may be partial value
net	Array	Sums of take-home income over 1-month periods. Current month may be partial value
confidence_score	Array	Confidence score for income over 1-month periods.

paystubs []

Example snippet of paystubs:

{
  "income": {
    ...
    "paystubs": [
      {
        "source_id": "OCROLUS",
        "source_record_id": "c33632a0-1d6a-11eb-806e-1f1356d092eb",
        "source_filepath": "f3f0d372-a0f7-402f-835e-67ce6db2a75f/866c943a-8e0b-45c6-b381-53712c2809a2.pdf",
        "employee_name": "PAYTON STUBBINS",
        "employee_address_line_1": "123 FRANKLIN ST",
        "employee_address_line_2": "APT 4",
        "employee_city": "CHAPEL HILL",
        "employee_state": "NC",
        "employee_zip": "27517",
        "pay_period_start": "2017-07-10",
        "pay_period_end": "2017-07-23",
        "pay_date": "2017-08-04",
        "pay_frequency": "SEMI_MONTHLY",
        "paystub_provider": "ADP",
        "hire_date": null,
        "net_total_earnings_amount_current": "1040.23",
        "net_total_earnings_amount_ytd": "18396.25",
        "gross_total_earnings_amount_current": "1627.74",
        "gross_total_earnings_amount_ytd": "28707.21",
        "regular_pay_earnings_amount_current": "1515.84",
        "regular_pay_earnings_amount_ytd": "24743.49",
        "bonus_earnings_amount_current": "40.69",
        "bonus_earnings_amount_ytd": "325.27",
        "overtime_earnings_amount_current": "0",
        "overtime_earnings_amount_ytd": "442.54",
        "commission_earnings_amount_current": null,
        "commission_earnings_amount_ytd": null,
        "paid_time_off_earnings_amount_current": "0",
        "paid_time_off_earnings_amount_ytd": "1459.97",
        "vacation_earnings_amount_current": "71.21",
        "vacation_earnings_amount_ytd": "952.9",
        "paid_time_off_deductions_amount_current": null,
        "paid_time_off_deductions_amount_ytd": null,
        "vacation_deductions_amount_current": null,
        "vacation_deductions_amount_ytd": null,
        "medicare_tax_deductions_amount_current": "22.12",
        "medicare_tax_deductions_amount_ytd": "394.81",
        "social_security_deductions_amount_current": "94.58",
        "social_security_deductions_amount_ytd": "1688.15",
        "fica_tax_deductions_amount_current": null,
        "fica_tax_deductions_amount_ytd": null,
        "regular_hours_earnings_current": "74.5",
        "regular_rate_earnings_current": "20.35",
        "commission_hours_earnings_current": null,
        "commission_rate_earnings_current": null,
        "overtime_hours_earnings_current": "0",
        "overtime_rate_earnings_current": null,
        "bonus_hours_earnings_current": "2",
        "bonus_rate_earnings_current": "20.35",
        "paid_time_off_hours_earnings_current": "0",
        "paid_time_off_rate_earnings_current": null,
        "vacation_hours_earnings_current": "3.5",
        "vacation_rate_earnings_current": "20.35",
        "annual_salary_rate": "45000",
        "pay_distribution": [
          {
            "bank_name": "BANK OF NOVA",
            "account_number": "0000987654321",
            "account_type": "CHECKING",
            "pay_amount_current": "1040.23"
          }
        ],
        "insights": {
          "insights_type": "NOVA_INSIGHTS",
          "insights_version": "1.0.0",
          "annual_earnings_insight": "45000",
          "annual_gross_income": "12345.67",
          "annual_net_income": "11234.56"
        },
        "consistency_checks": {
          "START_DATE_BEFORE_END_DATE": {
            "boolean_value": true
          },
          "GROSS_PAY_YTD_GREATER_THAN_OR_EQUAL_TO_GROSS_PAY_CURRENT": {
            "boolean_value": true
          },
          "NET_PAY_LESS_THAN_OR_EQUAL_TO_GROSS_PAY": {
            "boolean_value": true
          },
          "COMPONENT_EARNINGS_LESS_THAN_OR_EQUAL_TO_TOTAL_GROSS_PAY": {
            "boolean_value": true
          },
          "EMPLOYEE_NAME_EXISTS": {
            "boolean_value": true
          },
          "EMPLOYER_NAME_EXISTS": {
            "boolean_value": true
          },
          "START_DATE_IS_VALID_DATE": {
            "boolean_value": true
          },
          "END_DATE_IS_VALID_DATE": {
            "boolean_value": true
          },
          "PAY_DATE_IS_VALID_DATE": {
            "boolean_value": true
          },
          "START_DATE_EXISTS": {
            "boolean_value": true
          },
          "END_DATE_EXISTS":{
            "boolean_value": true
          },
          "PAY_DATE_EXISTS": {
            "boolean_value": true
          },
          "GROSS_TOTAL_EARNINGS_AMOUNT_CURRENT_EXISTS": {
            "boolean_value": true
          },
          "NET_TOTAL_EARNINGS_AMOUNT_CURRENT_EXISTS": {
            "boolean_value": true
          }
        },
        "irregularity_detection": {
          "status": "DETECTED",
          "irregularities": [
            {
                "type": "unusual_document_source",
                "details": [
                  {
                    "doc_origin": "Microsoft Office",
                  },
                ]
            },
            {
                "type": "page_edited",
                "details": [
                  {
                    "edit_source": "Adobe Acrobat",
                  },
                ]
            },
            {
                "type": "online_generated_paystub",
                "details": [
                  {
                    "site_name": "www.paystubcreator.net",
                  },
                ]
            },
            {
                "type": "dollar_amount_edits",
                "details": [
                  {
                    "field": "box:amount",
                    "tampered_text": "10,300.00",
                  },
                  {
                    "field": "box:periodDailyBalance",
                    "tampered_text": "13,495.00",
                    "original_text": "3,527.00",
                  },
                ]
            }
          ],
          "visualizations": [
            {
              "source_filepath": "f3f0d372-a0f7-402f-835e-67ce6db2a75f/2089b8e9-6fcc-412b-b5e6-c05a34032cf2.png",
              "description": "Tampered fields are highlighted in red.",
              "type": "tamper_overview"
            }
          ]
        },
      }
    ]
  },
}

Income information derived from paystub data.

Field	Format	Notes
source_id	String	The identifier for the source that reported the paystub information. See sources
source_record_id	UUID	The identifier for an individual record within a source
source_filepath	String	The file path used for downloading an applicants paystub file
employee_name	String	Name of applicant
employee_address_line_1	String	Address line 1 of applicant
employee_address_line_2	String	Address line 2 of applicant
employee_city	String	City of applicant
employee_state	String	State of applicant
employee_zip	String	Postal code of applicant
pay_period_start	Full Date	Start date of the paystub pay period
pay_period_end	Full Date	End date of the paystub pay period
pay_date	Full Date	Date the pay was issued
pay_frequency	String	See pay_frequency table
paystub_provider	String	Provider of paystub
hire_date	Full Date	Employee hire date as stated on the paystub
net_total_earnings_amount_current	String	Net total earnings from current pay period
net_total_earnings_amount_ytd	String	Net total earnings from year to date pay period
gross_total_earnings_amount_current	String	Gross total earnings from current pay period
gross_total_earnings_amount_ytd	String	Gross total earnings from year to date pay period
regular_pay_earnings_amount_current	String	Regular (base) pay earnings from current pay period
regular_pay_earnings_amount_ytd	String	Regular (base) pay earnings from year to date pay period
bonus_earnings_amount_current	String	Bonus earnings from current pay period period
bonus_earnings_amount_ytd	String	Bonus earnings from year to date pay period
overtime_earnings_amount_current	String	Overtime earnings from current pay period
overtime_earnings_amount_ytd	String	Overtime earnings from year to date pay period
commission_earnings_amount_current	String	Commission earnings from current pay period
commission_earnings_amount_ytd	String	Commission earnings from year to date pay period
paid_time_off_earnings_amount_current	String	Paid time off earnings from current pay period
paid_time_off_earnings_amount_ytd	String	Paid time off earnings from year to date pay period
vacation_earnings_amount_current	String	Vacation earnings from current pay period
vacation_earnings_amount_ytd	String	Vacation earnings from year to date pay period
paid_time_off_deductions_amount_current	String	Paid time off deductions from current pay period
paid_time_off_deductions_amount_ytd	String	Paid time off deductions from year to date pay period
vacation_deductions_amount_current	String	Vacation deductions from current pay period
vacation_deductions_amount_ytd	String	Vacation deductions from year to date pay period
medicare_tax_deductions_amount_current	String	Medicare tax deductions from current pay period
medicare_tax_deductions_amount_ytd	String	Medicare tax deductions from year to date pay period
social_security_deductions_amount_current	String	Social security tax deductions from current pay period
social_security_deductions_amount_ytd	String	Social security tax deductions from year to date pay period
fica_tax_deductions_amount_current	String	FICA tax deductions from current pay period
fica_tax_deductions_amount_ytd	String	FICA tax deductions from year to date pay period
regular_hours_earnings_current	String	Regular (base) hours earned from current pay period
regular_rate_earnings_current	String	Regular (base) average rate earned from current pay period
commission_hours_earnings_current	String	Commission hours earned from current pay period
commission_rate_earnings_current	String	Commission average rate earned from current pay period
overtime_hours_earnings_current	String	Overtime hours earned from current pay period
overtime_rate_earnings_current	String	Overtime average rate earned from current pay period
bonus_hours_earnings_current	String	Bonus hours earned from current pay period
bonus_rate_earnings_current	String	Bonus average rate earned from current pay period
paid_time_off_hours_earnings_current	String	Paid time off hours earned from current pay period
paid_time_off_rate_earnings_current	String	Paid time off average rate earned from current pay period
vacation_hours_earnings_current	String	Vacation hours earned from current pay period
vacation_rate_earnings_current	String	Vacation average rate earned from current pay period
annual_salary_rate	String	Employee annual salary rate as stated on the paystub
pay_distribution	Array	See pay_distribution
insights	Object	See insights
consistency_checks	Object	See consistency_checks
irregularity_detection	Object	See irregularity_detection

pay_distribution []

Example pay_distribution field object:
[
  {
    "bank_name": "BANK OF NOVA",
    "account_number": "0000987654321",
    "account_type": "CHECKING",
    "pay_amount_current": "1040.23"
  }
]

A list of payment distribution details

Field	Format	Notes
bank_name	String	Name of the bank where payment was distributed
account_number	String	The bank account number
account_type	String	Type of bank account. See account types
pay_amount_current	Float	Amount distributed

insights {}

Example insights field object:
{
  "insights": {
    "insights_type": "NOVA_INSIGHTS",
    "insights_version": "1.0.0",
    "annual_earnings_insight": "45000",
    "annual_gross_income": "12345.67",
    "annual_net_income": "11234.56"
  }
}

An object containing various insights from the paystub.

Field	Format	Notes
insights_type	String	See insights types
insights_version	String	The identifier for the paystub insights version
annual_earnings_insight	String	Annualized income insight based on paystub information, rounded to 2 decimal places
annual_gross_income	String	Annualized gross income based on paystub information, rounded to 2 decimal places
annual_net_income	String	Annualized net income based on paystub information, rounded to 2 decimal places

consistency_checks {}

Example consistency_checks field object:

{
  "consistency_checks": {
    "START_DATE_BEFORE_END_DATE": {
      "boolean_value": true
    },
    "GROSS_PAY_YTD_GREATER_THAN_OR_EQUAL_TO_GROSS_PAY_CURRENT": {
      "boolean_value": true
    },
    "NET_PAY_LESS_THAN_OR_EQUAL_TO_GROSS_PAY": {
      "boolean_value": true
    },
    "COMPONENT_EARNINGS_LESS_THAN_OR_EQUAL_TO_TOTAL_GROSS_PAY": {
      "boolean_value": true
    },
    "EMPLOYEE_NAME_EXISTS": {
      "boolean_value": true
    },
    "EMPLOYER_NAME_EXISTS": {
      "boolean_value": true
    },
    "START_DATE_IS_VALID_DATE": {
      "boolean_value": true
    },
    "END_DATE_IS_VALID_DATE": {
      "boolean_value": true
    },
    "PAY_DATE_IS_VALID_DATE": {
      "boolean_value": true
    },
    "START_DATE_EXISTS": {
      "boolean_value": true
    },
    "END_DATE_EXISTS":{
      "boolean_value": true
    },
    "PAY_DATE_EXISTS": {
      "boolean_value": true
    },
    "GROSS_TOTAL_EARNINGS_AMOUNT_CURRENT_EXISTS": {
      "boolean_value": true
    },
    "NET_TOTAL_EARNINGS_AMOUNT_CURRENT_EXISTS": {
      "boolean_value": true
    }
  }
}

An object containing various consistency checks for the paystub. Each check contains an object with a a boolean_value representing whether the check has passed or not.

Field	Notes
START_DATE_BEFORE_END_DATE	Indicates whether the start date of the pay period is before the end date of the pay period
GROSS_PAY_YTD_GREATER_THAN_OR_EQUAL_TO_GROSS_PAY_CURRENT	Indicates whether the year to date gross earnings are greater than or equal to the gross earnings for the pay period
NET_PAY_LESS_THAN_OR_EQUAL_TO_GROSS_PAY	Indicates whether the net earnings or less than or equal to the gross earnings
COMPONENT_EARNINGS_LESS_THAN_OR_EQUAL_TO_TOTAL_GROSS_PAY	Indicates whether the sum of the earnings components is less than or equal to the total gross pay
EMPLOYEE_NAME_EXISTS	Indicates whether the employee name was able to be determined from the paystub
EMPLOYER_NAME_EXISTS	Indicates whether the employer name was able to be determined from the paystub
START_DATE_IS_VALID_DATE	Indicates whether the start date of the pay period is an actual date on the Gregorian calendar
END_DATE_IS_VALID_DATE	Indicates whether the end date of the pay period is an actual date on the Gregorian calendar
PAY_DATE_IS_VALID_DATE	Indicates whether the pay date is an actual date on the Gregorian calendar
START_DATE_EXISTS	Indicates whether the start date of the pay period was able to be determined from the paystub
END_DATE_EXIST	Indicates whether the end date of the pay period was able to be determined from the paystub
PAY_DATE_EXISTS	Indicates whether the pay date was able to be determined from the paystub
GROSS_TOTAL_EARNINGS_AMOUNT_CURRENT_EXISTS	Indicates whether the gross total earnings was able to be determined from the paystub
NET_TOTAL_EARNINGS_AMOUNT_CURRENT_EXISTS	Indicates whether the net total earnings was able to be determined from the paystub

irregularity_detection {}

The irregularity detection node changes depending on the customer's configured fraud version. Please consult the section for your specific fraud version

• v1 and v2
• v3

Fraud v1 and v2

Example v1 irregularity_detection field object when irregularities are detected:

{
    "irregularity_detection": {
        "status": "DETECTED",
        "irregularities": [
            {
                "type": "unusual_document_source",
                "details": [
                    {
                        "doc_origin": "Microsoft Office"
                    }
                ]
            },
            {
                "type": "page_edited",
                "details": [
                    {
                        "edit_source": "Adobe Acrobat"
                    }
                ]
            },
            {
                "type": "online_generated_paystub",
                "details": [
                    {
                        "site_name": "www.paystubcreator.net"
                    }
                ]
            },
            {
                "type": "future_date",
                "details": [
                    {
                        "field": "Paystub Pay Date",
                        "processed_date": "2023-09-06",
                        "captured_date": "2023-09-08"
                    }
                ]
            },
            {
                "type": "dollar_amount_edits",
                "details": [
                    {
                        "field": "box:amount",
                        "tampered_text": "10,300.00"
                    },
                    {
                        "field": "box:periodDailyBalance",
                        "tampered_text": "13,495.00",
                        "original_text": "3,527.00"
                    }
                ]
            }
        ],
        "visualizations": [
            {
                "source_filepath": "f3f0d372-a0f7-402f-835e-67ce6db2a75f/2089b8e9-6fcc-412b-b5e6-c05a34032cf2.png",
                "description": "Tampered fields are highlighted in red.",
                "type": "tamper_overview"
            }
        ]
    }
}

Example v1/v2 irregularity_detection field object when irregularities are not detected:

{
    "irregularity_detection": {
        "status": "NOT_DETECTED",
        "irregularities": [],
        "visualizations": []
    }
}

Example v2 irregularity_detection field object when irregularities are not detected:

{
    "irregularity_detection": {
        "status": "NOT_DETECTED",
        "irregularities": [],
        "visualizations": [],
        "fraud_indication": [
            {
                "verdict": "TRUSTED",
                "file_type": "pdf",
                "indicators": "normal_object_sequence_per_document_class,normal_stream_operations,has_trusted_fonts,normal_metadata,is_pdf_unmodified_per_trailer_id",
                "reason_label": "Document is genuine and comes from a known issuer",
                "reason_value": "TRUSTED_PDF"
            }
        ]
    }
}

Example v2 irregularity_detection field object when irregularities are detected:

{
  "irregularity_detection": {
    "status": "DETECTED",
        "irregularities": [
            {
                "type": "unusual_document_source",
                "details": [
                    {
                        "doc_origin": "ipsam"
                    }
                ]
            }
        ],
        "visualizations": [
            {
                "source_filepath": "aa418d6a-dad5-490f-be7e-e3279a6f222b/74fd69bc-f278-453c-ba9f-bc751e028baf.png",
                "description": "Tampered fields are highlighted in red.",
                "type": "tamper_overview"
            }
        ]
    "fraud_indication": {
            "verdict": "WARNING",
            "file_type": "image",
            "indicators": "screenshot,has_smartphone_header_footer",
            "reason_label": "Document created by capturing an image from a device screen",
            "reason_value": "SCREENSHOT"
        }
  }
}

This node will contain details about any irregularities detected.

Field	Format	Notes
status	String	See irregularity_detection_status values
irregularities	Array	See irregularities
visualizations	Array	See visualizations
fraud_indication	Array	(optional) See fraud_indication

irregularities []

Example irregularities array:

{
    "irregularities": [
      {
          "type": "account_number_edits",
          "details": [
            ...
          ]
      },
      ...
}

An array with each instance describing a distinct type of irregularity found on the file. This array will be empty unless irregularity_detection.status is DETECTED.

Field	Format	Notes
type	String	See irregularity types
details	Array	See details

details []

Example details array when irregularity `type` is `page_edited`:

{
    "details": [
      {
         "edit_source": "Adobe Acrobat",
      }
    ]
}

Example details array when irregularity `type` is `unusual_document_source`:

{
    "details": [
      {
         "doc_origin": "Microsoft Office",
      }
    ]
}

Example details array when irregularity `type` is `online_generated_paystub`:

{
    "details": [
      {
         "site_name": "www.paystubcreator.net",
      }
    ]
}

Example details array when irregularity `type` is `future_date`:

{
    "details": [
      {
         "field": "Paystub Pay Date",
         "captured_date": "2023-09-08",
         "processed_date": "2023-09-06",
      }
    ]
}

Example details array for all other irregularity `type`s:

{
    "details": [
      {
        "field": "accountInfo:accountHolderName",
        "original_text": "George Eliot",
        "tampered_text": "Mary Ann Evans"
      },
      ...
    ]
}

An array with each instance describing a distinct instance of an irregularity found on the file. There are 3 possible object shapes in this array, depending on the irregularity type it represents.

Field	Format	Notes
field	String	(optional) The name of the field that has been edited
original_text	String	(optional) The recovered text that was originally on the document
tampered_text	String	(optional) The text that now appears on the document
edit_source	String	(optional) Present when irregularity type is page_edited. The name of the software used to edit the page
doc_origin	String	(optional) Present when irregularity type is unusual_document_source. The original source of the document
site_name	String	(optional) Present when irregularity type is online_generated_paystub. The site used to generate the document
processed_date	String	(optional) Present when irregularity type is future_date. The processing date of the document
captured_date	String	(optional) Present when irregularity type is future_date. The captured date of the document
processed_year	String	(optional) Present when irregularity type is future_year. The processing year of the document
captured_year	String	(optional) Present when irregularity type is future_year. The captured year of the document

visualizations []

Example snippet of visualizations:

{
  "visualizations": [
    {
      "source_filepath": "f3f0d372-a0f7-402f-835e-67ce6db2a75f/2089b8e9-6fcc-412b-b5e6-c05a34032cf2.png",
      "description": "Tampered fields are highlighted in red.",
      "type": "tamper_overview"
    },
    ...
  ]
}

An array of irregularity visualization metadata objects. This array will be empty unless irregularity_detection.status is DETECTED.

Field	Format	Notes
source_filepath	String	The file path used for downloading the visualizations file
description	String	A human-readable description of the visualized fraud signal and guidance on how to interpret it
type	String	The type of file tampering visualization offered in this image

fraud_indication []

Example snippet of fraud_indication:

{
  "fraud_indication": [
    {
      "verdict": "TRUSTED",
      "file_type": "pdf",
      "indicators": "normal_object_sequence_per_document_class,normal_stream_operations,has_trusted_fonts,normal_metadata,is_pdf_unmodified_per_trailer_id",
      "reason_label": "Document is genuine and comes from a known issuer",
      "reason_value": "TRUSTED_PDF"
    },
    ...
  ]
}

fraud_indication is an alternative / augmentative service to irregularities. They can be returned alone or alongside the detected irregularities.

Field	Format	Notes
verdict	String	See fraud_indication_verdict values
file_type	String	See fraud_indication_file_type values
indicators	String	A comma-separated string of specific positive/negative fraud indicators found in the file
reason_label	String	Plaintext description for the reason_value
reason_value	String	More specific reason for the verdict value

Fraud v3

If Irregularity Detection is enabled, this node will contain details about any irregularities detected.

Field	Format	Notes
status	String	See irregularity_detection_status values
reasons	Array	See irregularity_detection_reasons values
file_type	String	See irregularity_detection_file_types values
genuine_pdf	Boolean	True only if document is exceptionally genuine, not provided otherwise
version	String	The version of the fraud algorithm used to generate the results

Example irregularity_detection field with status NOT_DETECTED and the genuine_pdf flag:

{
    "irregularity_detection": {
        "status": "NOT_DETECTED",
        "reasons": [],
        "file_type": "pdf",
        "genuine_pdf": true,
        "version": "3.0"
    }
}

Example irregularity_detection field with status REVIEW:

{
    "irregularity_detection": {
        "status": "REVIEW",
        "reasons": [
            {
                "reason": "Edited Content Detected",
                "severity": "Low Risk"
            }
        ],
        "file_type": "pdf",
        "version": "3.0"
    }
}

Example irregularity_detection field with status DETECTED and multiple reasons:

{
    "irregularity_detection": {
        "status": "DETECTED",
        "reasons": [
            {
                "reason": "Edited Content Detected",
                "severity": "High Risk"
            },
            {
                "reason": "Unusual Document Source Detected",
                "severity": "Medium Risk"
            }
        ],
        "file_type": "pdf",
        "version": "3.0"
    }
}

irregularity detection reasons []

Specific reasons supporting the provided irregularity_detection status.

Field	Format	Notes
reason	String	See the irregularity_detection_reason table
severity	String	See the irregularity_detection_severity table

payroll []

Example snippet of payroll:

{
  "income": {
    ...
    "payroll": [
      {
        "source_id": "USA_ATOMIC",
        "provider_name": "ADP",
        "annual_income": 45000.54,
        "annual_salary_rate": 45000.54,
        "estimated_gross_annual_income": 47500.38,
        "estimated_net_annual_income": 30000.12,
        "pay_frequency": "WEEKLY",
        "pay_period_start": "2020-06-13",
        "pay_period_end": "2020-06-27",
        "statements": [
          {
            "source_id": "USA_ATOMIC",
            "pay_date": "2020-06-30",
            "gross_total_earnings_amount_current": 1225,
            "gross_total_earnings_amount_ytd": 13625,
            "net_total_earnings_amount_current": 840,
            "net_total_earnings_amount_ytd": 8840
          },
          {
            "source_id": "USA_ATOMIC",
            "pay_date": "2020-06-15",
            "gross_total_earnings_amount_current": 1175,
            "gross_total_earnings_amount_ytd": 12400,
            "net_total_earnings_amount_current": 800,
            "net_total_earnings_amount_ytd": 8000
          }
        ]
      }
    ]
  }
}

Income information derived from payroll data.

Field	Format	Notes
source_id	String	The identifier for the source that reported the payroll information. See sources
provider_name	String	Name of the provider of payroll
annual_income	Float	Deprecated. Use annual_salary_rate or estimated_gross_annual_income instead.
annual_salary_rate	Float	Employee annual salary rate as reported by the payroll provider. Will be null if not provided
estimated_gross_annual_income	Float	Estimate of the gross annual income
estimated_net_annual_income	Float	Estimate of the net annual income
pay_period_start	Full Date	Start date of the payroll pay period
pay_period_end	Full Date	End date of the payroll pay period
pay_frequency	String	See pay_frequency table
statements	Array	See statements

statements []

Example statements field object:
[
  {
    "source_id": "USA_ATOMIC",
    "pay_date": "2020-06-15",
    "gross_total_earnings_amount_current": 1175,
    "gross_total_earnings_amount_ytd": 12400,
    "net_total_earnings_amount_current": 800,
    "net_total_earnings_amount_ytd": 8000
  }
]

A list of statement details

Field	Format	Notes
source_id	String	The identifier for the source that reported the payroll information. See sources
pay_date	Full Date	Date the pay was issued
gross_total_earnings_amount_current	Float	Gross total earnings from current pay period
gross_total_earnings_amount_ytd	Float	Gross total earnings from year to date pay period
net_total_earnings_amount_current	Float	Net total earnings from current pay period
net_total_earnings_amount_ytd	Float	Net total earnings from year to date pay period

metrics []

Example snippet of metrics in the report response:

{
  "metrics": [
    {
      "source_ids": ["USA_FIN"],
      "metric_status": "AVAILABLE",
      "metric_source": "NOVA",
      "metric_name": "AVG_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS",
      "metric_value": 3200,
      "metric_label": "Average of Net on Financial Accounts Last 6 Months",
      "metric_format": "NUMERIC",
      "metric_type": "CURRENCY"
    },
    {
      "source_ids": ["USA_FIN"],
      "metric_status": "AVAILABLE",
      "metric_source": "NOVA",
      "metric_name": "MIN_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS",
      "metric_value": 500,
      "metric_label": "Minimum of Net on Financial Accounts Last 6 Months",
      "metric_format": "NUMERIC",
      "metric_type": "CURRENCY"
    },
    ...
  ],
}

Metrics are analytical values derived from the underlying data in the report. metrics are returned in an array and are of configurable length; the array can have zero objects, and there is no upper bound.

Not all sources include metrics. Bank transaction sources will include these metrics in every response:

• TREND_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS
• AVG_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS
• MIN_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS
• MAX_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS

It is possible that you will want to reconfigure these metrics after your initial integration with our API; please consider an approach that permits adding and removing metrics without incurring additional integration work. If you have configured customized metrics, or intend to in the future, please contact your Nova Credit Representative for additional examples, details, and advice. It is particularly important that you discuss the mechanics of your metric integration if it relies on a fixed ordering or maximum number of metrics.

Note that if attributes are enabled, metrics will not be available in the report response.

Field	Format	Notes
source_ids	Array	A list of ids of the sources utilized to generate this metric. See sources
metric_name	String	See metric_name
metric_value	Number/Boolean	Value of the metric. Can be numeric or a boolean value.
metric_status	String	See metric_status
metric_source	String	See metric_source
metric_label	String	See metric_label
metric_type	String	See metric_type
metric_format	String	See metric_format

attributes []

info

Please note that this feature is only available for select customers. Contact your Nova Credit Representative to learn more. Note that if attributes are enabled, metrics will not be available in the report response.

Example snippet of attributes in the report response:

{
  "attributes": [
    {
      "name": "ASSETS_CASH_EQUIVALENT_BALANCE",
      "description": "Current cash equivalent balance on assets",
      "node":  "ASSETS",
      "source_ids": ["USA_FIN"],
      "value": 3200,
      "adverse_action_code": "21"
    },
    {
      "name": "ASSETS_CURRENT_RATIO",
      "description": "Current ratio on assets",
      "node": "ASSETS",
      "source_ids": ["USA_FIN"],
      "value": 9999998,
      "adverse_action_code": "25"
    },
    ...
  ],
}

Attributes are analytical values derived from the underlying data in the report. attributes are returned in an array; the array can have zero objects, and there is no upper bound. Please consider an approach that permits adding and removing attributes without incurring additional integration work. It is particularly important that you discuss the mechanics of your attributes integration if it relies on a fixed ordering or maximum number of attributes.

Attributes exist at the account level applicable to only the data for a specific connected account or at the aggregate report level consolidated across all connected accounts.

Field	Format	Notes
name	String	The name of the attribute
description	String	Human readable description of the attribute
node	String	See node_type
source_ids	Array	A list of IDs of the sources utilized to generate this attribute. See sources
value	Number	Value of the attribute. See value types
adverse_action_code	String	See adverse_action_codes

Calculations

This service retrieves up to two years of transaction history for the consumer’s provided accounts. This data is grouped based on the transaction posted date and used to generate attributes. This grouping is used to determine which data points will be used to calculate an attribute that is bound by a time frame. If an explicit time frame is given, then the data used to compute the attribute will only include data points for past complete months.

For example, an attribute that calculates the average number of expense transactions over a 12 month period when the consumer completed the application on February 17, 2022 will only include data points between January 1, 2021 to January 31, 2022 inclusive.

In the event an attribute calculation results in an infinite or undefined number, such as dividing by 0, a cap value will be returned.

Calculation	Format	Notes
Average	Integer	The average value over the specified duration
Minimum	Integer	The minimum value over the node's history over the specified duration
Maximum	Integer	The maximum value over the node's history over the specified duration
Trend	Integer	Calculate the slope of the values over the specified duration
Sum	Integer	The sum of all values over the specified duration
Ratio	Float	The ratio between two different sets of data
Count	Integer	The number of occurrences a qualification nis met over the specified duration
Boolean	Boolean	True or false
Recency	Integer	Counts the number of days that fit the given qualification over the specified duration
Balance	Float	Calculate the dollar amount balance over the specified duration. Only two places after the decimal are returned

Default Condition Values

In the case that an attribute could not be calculated, an integer value will be returned indicating one of three scenarios. See Value Types for a table on values based on type.

Condition	Description
No usable records	No relevant records were found for the given node type. This typically occurs in scenarios such as when the user did not connect any accounts or no transactions were found across all connected accounts
No usable records in the category	Records exist for the node, but not for the attribute's sub category
No usable values	Records exist for the node and category, but the records do not match a constraint such as time frame

Value Types

Type	Minimum Value	Maximum Value	Cap Value	No Usable Records	No Usable records in the Category	No Usable Values
Boolean	0	1	5	8	7	6
Dollar Amounts	-9,999,999.99	9,999,994.99	9,999,995	9,999,998	9,999,997	9,999,996
Float	-9,999,999.99999	9,999,994.99999	9,999,995	9,999,998	9,999,997	9,999,996
Short Integer	-9,999	9,9994	9,995	9,998	9,997	9,996
Long Integer	-9,999,999	9,999,994	9,999,995	9,999,998	9,999,997	9,999,996

adverse_action_codes []

adverse_action_codes give information about the key factors that affect the consumer’s score. The requirement for lenders to send adverse action notices is a part of the Fair Credit Reporting Act (FCRA), a federal law that promotes accuracy, fairness, and privacy of information.

adverse_action_codes are returned in an array of objects. Each attribute maps to one specific adverse action code, and the adverse_action_codes array will only contain the codes that are associated with attributes found in the attributes node of the API response.

This node will be visible only if the attributes node is enabled.

Field	Format	Notes
code	String	Numeric code between 00 and 100, exclusive. Reach out to your Nova representative to retrieve the values of each code.
description	String	Human readable description

Tables

account_type

Values of the account_type field.

Value
CHECKING
SAVINGS
INVESTMENT
MONEY_MARKET
OTHER

inquiry_type

The human-readable labels are shown when creating and viewing products in the Nova Credit Dashboard. The value column shows the values that are returned in the JSON.

Human-readable label	Value
Monitoring	MONITORING
Credit Card	CREDIT_CARD
Vehicle Auto	VEHICLE_AUTO
Vehicle Other	VEHICLE_OTHER
Mortgage	MORTGAGE
Personal	PERSONAL
Student	STUDENT
Utility	UTILITY
Commercial	COMMERCIAL
Consumer	CONSUMER
Tenant Screening	TENANT
Other	OTHER

metric_name

Values of the metric_name field. To configure the set of metrics provided in your API response or to request additional custom metrics, contact your Nova Credit Representative. This list should be considered non-exhaustive and may be expanded in the future.

Name	Label
TREND_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS	Most recent monthly history value minus the oldest monthly history value within the previous six months
AVG_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS	Average monthly history value based on history array observations within the previous six months
MIN_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS	Minimum monthly history value based on history array observations within the previous six months
MAX_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS	Maximum monthly history value based on history array observations within the previous six months

metric_status

Values of the metric_status field.

Value	Description
AVAILABLE	Metric is available for this report
UNAVAILABLE_REPORT	Metric is unavailable for this report due to lack of underlying data

metric_source

Values of the metric_source field.

Value	Description
NOVA	This data was calculated from the report data by Nova Credit

metric_label

Values of the metric_label field. See metric_name

metric_type

Values of the metric_type field.

Value	Description
INTEGER	This data is an integer
CURRENCY	This data is a currency
BOOLEAN	This data is a boolean

metric_format

Values of the metric_format field.

Value	Description
NUMERIC	This data is an individual numeric value

model_type

Values of the model_type field.

Value	Description
NOVA_INCOME	The Nova Credit Income Model

node_type

Select top level nodes from the report body that are associated with an attribute. At this time, not all node types may be available at the top level of the report. Certain category of attributes will belong to one of the existing node types.

Value	Categories
ASSETS	Cash equivalent accounts, investment accounts
DEBTS	Real estate, installment accounts, revolving, other accounts, short term, overdraft
EXPENSES	NSFs (Non-sufficient funds)
INCOME	Net income, cash flow

insights_type

Values of the insights_type field.

Value	Description
NOVA_INSIGHTS	The Nova Credit Insights

pay_frequency

Values of the pay_frequency field.

Value
null
MONTHLY
BI_WEEKLY
WEEKLY
SEMI_MONTHLY

Fraud v1 and v2

irregularity_detection_status

Values of the status field in the v1/v2 irregularity_detection node. Derived from irregularities, fraud_indication, or both if both are enabled.

Value	Description
NOT_DETECTED	No irregularities or fraud indications were detected on the file
DETECTED	Irregularities or fraud indications detected, and will be described in the irregularities, visualizations, or fraud_indication subnodes
REVIEW	Minor fraud indications detected, manual review recommended
TIMED_OUT	Irregularity detection did not complete in time for report compilation
DATA_SUPPLIER_ERROR	There was an error while running irregularity detection

irregularity_type

Possible values of the type field in the irregularities subnode.

Value	Note
page_edited	Will result in a unique details object shape
unusual_document_source	Will result in a unique details object shape
online_generated_paystub	Will result in a unique details object shape
account_number_edits
employee_taxpayer_id_edits
employer_id_edits
account_holder_edits
employer_name_edits
account_holder_address_edits
employer_address_edits
account_type_edits
employee_name_edits
employee_address_edits
dollar_amount_edits
earnings_edits
deductions_edits
withholdings_edits
date_edits
transaction_description_edits
pay_frequency_edits
other_edits
employee_details_edits
future_date
suspicious_address
suspected_template

fraud_indication_verdict

Possible values of the verdict field in the fraud_indication subnode.

Value	Description
NORMAL	No particular reason to trust or distrust document
TRUSTED	Reasons to trust document have been identified
WARNING	Document is more likely to have been modified (such as a scanned document)
HIGH_RISK	Document modifications were identified that are frequently associated with fraud or forgery attempts

fraud_indication_file_type

Possible values of the file_type field in the fraud_indication subnode.

Value
pdf
image
unsupported

Fraud v3

irregularity_detection_status

Values of the status field in the v3 irregularity_detection node.

Value	Description
NOT_DETECTED	No irregularities were detected on the file
DETECTED	Irregularities were detected on the file
REVIEW	Minor fraud indications detected, manual review recommended

irregularity_detection_file_type

Values of the file_type field in the irregularity_detection node.

Value
pdf
image
unsupported

irregularity_detection_reason

Values of the reason field in the v3 irregularity_detection reasons node.

Value
Serial Fraud Detected
Edited Content Detected
Suspicious Modification Detected
Browser/Os Processed
No Textual Document Detected
Unusual Document Source Detected
Screenshot Detected
PDF/Image Converted
Suspicious Format Detected
Editing Software Detected
Others

irregularity_detection_severity

Values of the severity field in the v3 irregularity_detection reasons node.

Value
High Risk
Medium Risk
Low Risk

source_type

Values of the source_type field.

Value	Description
BANK_TRANSACTION	Data was sourced from a bank connection
EMPLOYMENT	Data was sourced from an uploaded paystub
PAYROLL	Data was sourced from a payroll provider
CONSUMER_INPUT	Data was manually entered by the applicant

substatus

Additional insight on certain cases that occur when fetching or parsing a report.

These substatuses may accompany a report with a SUCCESS status:

Value	Description
ACCOUNT_TOO_NEW	The account linked does not have any inflow transactions that are older than 3 months.
NO_RECENT_USABLE_INFORMATION	There are no transactions or accounts for this report. The income node will not be attached.
NO_USABLE_INCOME_INFORMATION	There are no income streams for this report with sufficient confidence scores or the income data cannot be grouped into streams. The income node will not be attached.

These substatuses may accompany a webhook with an ERROR status:

Value	Description
MFA_REQUIRED_ON_FETCH	The bank account the user tried to connect to requires multi-factor authentication and may depend on the user's browser security settings.
INCOMPATIBLE_ACCOUNT_TYPES_SUBMITTED	The user only submitted debt accounts (e.g. credit card).
INCOMPLETE_INFORMATION	The source did not provide critical fields
INVALID_PREFILLS_PII_MISSING	Must provide all required prefill fields.
INVALID_PREFILL_ADDRESS	The address sent via prefill must be a string with max length 100 and contain a valid street address.
INVALID_PREFILL_CITY	The city sent via prefill must be a string with max length 100.
INVALID_PREFILL_DOB	The birthday sent via prefill is missing or not in YYYY-MM-DD format.
INVALID_PREFILL_EMAIL	The email sent via prefill must be a valid email with max length 100.
INVALID_PREFILL_FIRST_NAME	The first name sent via prefill must be a string less than 255 characters and contain only alphabetical, unicode, dots, apostraphes and dashes.
INVALID_PREFILL_LAST_NAME	The last name sent via prefill must be a string less than 255 characters and contain only alphabetical, unicode, dots, apostraphes and dashes.
INVALID_PREFILL_INCOME	The stated annual income sent via prefill must be an integer between 0 and 2147483647.
INVALID_PREFILL_PHONE	The phone number sent via prefill must be a string with max length 255.
INVALID_PREFILL_STATE	The state sent via prefill is missing or not in a valid two letter US state or territory code.
INVALID_PREFILL_ZIP	The zip code sent via prefill must a string with a valid USA zip code.

These substatuses may accompany a webhook with a NON_CONTRIBUTING_APPLICANT status:

Value	Description
COAPPLICANT_GUARANTOR_PROVIDING	The applicant selected to not contribute income because their co-applicant or guarantor will provide income instead.

responsibility

Values of the responsibility field.

Value	Description
INDIVIDUAL	The individual is solely responsible for the account
JOINT	The individual is jointly responsible for the account

Cash Atlas Response

This is a sample response of the Cash Atlas report. Not all possible data values are present.

{
  "meta": {
    "user_args": "22bbd586-12b9-4876-8ec0-d210d081f4a1|email@test.com",
    "created_at": "2020-04-07T00:53:43.829Z",
    "api_version": "4.6.93",
    "public_token": "e3f60d3a-8a22-4940-9d1e-50f4f9878503"
  },
  "product": {
    "product_id": "c3a37c41-7c62-11e7-8141-19157d9a48c7",
    "name": "Pascoe Gardens Sandbox",
    "inquiry_type": "TENANT"
  },
  "sources": [
    {
      "source_id": "USA_FIN",
      "source_type": "BANK",
      "status": "SUCCESS"
    },
    {
      "source_id": "CONSUMER_INPUT",
      "source_type": "MANUAL",
      "status": "SUCCESS"
    }
  ],
  "identities": [{
    "source_id": "CONSUMER_INPUT",
    "first_name": "Raymond",
    "last_name": "Marshal",
    "emails": ["raymond@email.com"]
  }],
  "employment": [
    {
      "source_id": "OCROLUS",
      "employer_name": "NAPOLI PIZZERIA",
      "employer_legal_name": "NAPOLI PIZZERIA INC",
      "employer_address_line_1": "1 Pepperoni Way",
      "employer_address_line_2": null,
      "employer_city": "Redmond",
      "employer_state": "Washington",
      "employment_type": "fulltime",
      "employment_status":"active"
      "job_title": "Product Manager",
      "hire_date": null,
    }
  ],
  "bank_transactions": [{
    "summary": {
      "source_id": "USA_FIN",
      "months_available": 6
    },
    "account_details": [{
      "account_id": "36139831-0a91-4d1f-bc3e-edc908a978c6",
      "owner_full_name": "John Doe",
      "institution_name": "CHASE",
      "account_name": "INVESTMENT ACCOUNT",
      "account_type": "INVESTMENT",
      "date_opened": "2015-05-01",
      "oldest_transaction_date": "2015-05-03",
      "truncated_account_number": "1234",
      "responsibility": "INDIVIDUAL",
      "last_statement_end_date": "2015-05-30",
      "addresses": [
        {
          "address_id": "80421b7e-7918-4963-b5fb-85055c2994b7",
          "address": "225 Valencia St.",
          "street": "Valencia St.",
          "city": "San Francisco",
          "zipcode": "94103",
          "state": "CA"
        }
      ],
      "current_balance": 45971,
      "routing_number": "98164521",
      "full_account_number": "01885674",
       "attributes": [
        {
          "name": "EXPENSES_COUNT_3_MONTH_AVG",
          "description": "Average count of expenses over the last 3 months",
          "node": "EXPENSES",
          "source_ids": ["USA_FIN"],
          "adverse_action_code": "66",
          "value": 10
        },
        {
          "name": "EXPENSES_COUNT_0_50_3_MONTH_AVG",
          "description": "Average count of expenses between $0 and $50 over the last 3 months",
          "node": "EXPENSES",
          "source_ids": ["USA_FIN"],
          "adverse_action_code": "67",
          "value": 9996
        },
        ...
      ],
    }],
    "inflows": {
      "total_annual": 24000,
      "total_adjusted_annual": 27600,
      "history": [
        {
          "year": 2019,
          "total": [ null, 2000, ... ],
          "misc_deposits": [ null, 100, ... ]
        },
      ],
    },
  }],
  "expenses": [{
      "history": [
        {
          "year": 2019,
          "count": [ null, null, null, null, null, null, 1, 2, 3, 1, 1, 1 ],
          "count_0_50": [ null, null, null, null, null, null, 0, 0, 0, 0, 0, 0 ],
          "count_50_100": [ null, null, null, null, null, null, 0, 0, 1, 0, 0, 0 ],
          "count_100_250": [ null, null, null, null, null, null, 0, 0, 0, 0, 0, 0 ],
          "count_250_500": [ null, null, null, null, null, null, 0, 1, 0, 0, 0, 0 ],
          "count_500_1000": [ null, null, null, null, null, null, 0, 0, 0, 0, 0, 0 ],
          "count_above_1000": [ null, null, null, null, null, null, 1, 1, 2, 1, 1, 1 ],
          "sum": [ null, null, null, null, null, null, 1056, 1456, 2942, 1056, 1056, 1056 ],
          "sum_0_50": [ null, null, null, null, null, null, 0, 0, 0, 0, 0, 0 ],
          "sum_50_100": [ null, null, null, null, null, null, 0, 0, 70, 0, 0, 0 ],
          "sum_100_250": [ null, null, null, null, null, null, 0, 0, 0, 0, 0, 0 ],
          "sum_250_500": [ null, null, null, null, null, null, 0, 400, 0, 0, 0, 0 ],
          "sum_500_1000": [ null, null, null, null, null, null, 0, 0, 0, 0, 0, 0 ],
          "sum_above_1000": [ null, null, null, null, null, null, 1056, 1056, 2872, 1056, 1056, 1056 ],
        },
      ],
    }],
  "income": {
    "financial_accounts": [
      {
        "source_ids": ["USA_FIN"],
        "model_version": "0.1.5",
        "model_type": "NOVA_INCOME",
        "descriptions": ["GUSTO PAY", "NAPOLI PIZZERIA DIR DEP"],
        "is_consistent": true,
        "net_recent": 20000,
        "gross_recent": 24000,
        "confidence_score_recent": 90,
        "net_annual": 20000,
        "gross_annual": 24000,
        "confidence_score_annual": 90,
        "matched_income": {
          "stated_employer": "Napoli Pizzeria",
          "stated_annual_income": 18000,
          "description": "NAPOLI PIZZERIA USA 6787 836XNLNKSEYCQ8B -",
          "net_income": 15480,
          "gross_income": 18923,
          "confidence_score": 80,
        },
        "history": [
          {
            "year": 2019,
            "gross": [ 2500, 5000, ... ],
            "net": [ 2250, 4500, ... ],
            "confidence_score": [90, 90, ...],
          },
        ]
      },
    ],
    "paystubs": [
      {
        "source_id": "OCROLUS",
        "source_record_id": "c33632a0-1d6a-11eb-806e-1f1356d092eb",
        "source_filepath": "f3f0d372-a0f7-402f-835e-67ce6db2a75f/866c943a-8e0b-45c6-b381-53712c2809a2",
        "employee_name": "JOHN DOE",
        "employee_address_line_1": "123 FRANKLIN ST",
        "employee_address_line_2": "APT 4",
        "employee_city": "CHAPEL HILL",
        "employee_state": "NC",
        "employee_zip": "27517",
        "pay_period_start": "2017-07-10",
        "pay_period_end": "2017-07-23",
        "pay_date": "2017-08-04",
        "pay_frequency": "SEMI_MONTHLY",
        "paystub_provider": "ADP",
        "hire_date": null,
        "net_total_earnings_amount_current": "1040.23",
        "net_total_earnings_amount_ytd": "18396.25",
        "gross_total_earnings_amount_current": "1627.74",
        "gross_total_earnings_amount_ytd": "28707.21",
        "regular_pay_earnings_amount_current": "1515.84",
        "regular_pay_earnings_amount_ytd": "24743.49",
        "bonus_earnings_amount_current": "40.69",
        "bonus_earnings_amount_ytd": "325.27",
        "overtime_earnings_amount_current": "0",
        "overtime_earnings_amount_ytd": "442.54",
        "commission_earnings_amount_current": null,
        "commission_earnings_amount_ytd": null,
        "paid_time_off_earnings_amount_current": "0",
        "paid_time_off_earnings_amount_ytd": "1459.97",
        "vacation_earnings_amount_current": "71.21",
        "vacation_earnings_amount_ytd": "952.9",
        "paid_time_off_deductions_amount_current": null,
        "paid_time_off_deductions_amount_ytd": null,
        "vacation_deductions_amount_current": null,
        "vacation_deductions_amount_ytd": null,
        "medicare_tax_deductions_amount_current": "22.12",
        "medicare_tax_deductions_amount_ytd": "394.81",
        "social_security_deductions_amount_current": "94.58",
        "social_security_deductions_amount_ytd": "1688.15",
        "fica_tax_deductions_amount_current": null,
        "fica_tax_deductions_amount_ytd": null,
        "regular_hours_earnings_current": "74.5",
        "regular_rate_earnings_current": "20.35",
        "commission_hours_earnings_current": null,
        "commission_rate_earnings_current": null,
        "overtime_hours_earnings_current": "0",
        "overtime_rate_earnings_current": null,
        "bonus_hours_earnings_current": "2",
        "bonus_rate_earnings_current": "20.35",
        "paid_time_off_hours_earnings_current": "0",
        "paid_time_off_rate_earnings_current": null,
        "vacation_hours_earnings_current": "3.5",
        "vacation_rate_earnings_current": "20.35",
        "annual_salary_rate": "45000",
        "pay_distribution": [
          {
            "bank_name": "BANK OF NOVA",
            "account_number": "0000987654321",
            "account_type": "CHECKING",
            "pay_amount_current": "1040.23"
          }
        ],
        "insights": {
          "insights_type": "NOVA_INSIGHTS",
          "insights_version": "1.0.0",
          "annual_earnings_insight": "45000"
        },
        "consistency_checks": {
          "START_DATE_BEFORE_END_DATE": {
            "boolean_value": true
          },
          "GROSS_PAY_YTD_GREATER_THAN_OR_EQUAL_TO_GROSS_PAY_CURRENT": {
            "boolean_value": true
          },
          "NET_PAY_LESS_THAN_OR_EQUAL_TO_GROSS_PAY": {
            "boolean_value": true
          },
          "COMPONENT_EARNINGS_LESS_THAN_OR_EQUAL_TO_TOTAL_GROSS_PAY": {
            "boolean_value": true
          },
          "EMPLOYEE_NAME_EXISTS": {
            "boolean_value": true
          },
          "EMPLOYER_NAME_EXISTS": {
            "boolean_value": true
          },
          "PAY_DATE_EXISTS": {
            "boolean_value": true
          },
          "GROSS_TOTAL_EARNINGS_AMOUNT_CURRENT_EXISTS": {
            "boolean_value": true
          },
          "NET_TOTAL_EARNINGS_AMOUNT_CURRENT_EXISTS": {
            "boolean_value": true
          }
        },
        "irregularity_detection": {
          "status": "DETECTED",
          "irregularities": [
            {
                "type": "unusual_document_source",
                "details": [
                  {
                    "doc_origin": "Microsoft Office",
                  },
                ]
            },
            {
                "type": "page_edited",
                "details": [
                  {
                    "edit_source": "Adobe Acrobat",
                  },
                ]
            },
            {
                "type": "dollar_amount_edits",
                "details": [
                  {
                    "field": "box:amount",
                    "tampered_text": "10,300.00",
                  },
                  {
                    "field": "box:periodDailyBalance",
                    "tampered_text": "13,495.00",
                    "original_text": "3,527.00",
                  },
                ]
            }
          ],
          "visualizations": [
            {
              "source_filepath": "f3f0d372-a0f7-402f-835e-67ce6db2a75f/2089b8e9-6fcc-412b-b5e6-c05a34032cf2.png",
              "description": "Tampered fields are highlighted in red.",
              "type": "tamper_overview"
            }
          ]
        }
      }
    ]
  },
  "metrics": [
    {
      "source_ids": ["USA_FIN"],
      "metric_status": "AVAILABLE",
      "metric_source": "NOVA",
      "metric_name": "AVG_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS",
      "metric_value": 3200,
      "metric_label": "Average of Net on Financial Accounts Last 6 Months",
      "metric_format": "NUMERIC",
      "metric_type": "CURRENCY"
    },
    {
      "source_ids": ["USA_FIN"],
      "metric_status": "AVAILABLE",
      "metric_source": "NOVA",
      "metric_name": "MIN_INCOME_FINANCIAL_ACCOUNTS_NET_LAST_6_MONTHS",
      "metric_value": 500,
      "metric_label": "Minimum of Net on Financial Accounts Last 6 Months",
      "metric_format": "NUMERIC",
      "metric_type": "CURRENCY"
    },
  ],
  "attributes": [
    {
      "name": "EXPENSES_COUNT_3_MONTH_AVG",
      "description": "Average count of expenses over the last 3 months",
      "node": "EXPENSES",
      "source_ids": ["USA_FIN"],
      "adverse_action_code": "66",
      "value": 10
    },
    {
      "name": "EXPENSES_COUNT_0_50_3_MONTH_AVG",
      "description": "Average count of expenses between $0 and $50 over the last 3 months",
      "node": "EXPENSES",
      "source_ids": ["USA_FIN"],
      "adverse_action_code": "67",
      "value": 9996
    },
    ...
  ],
}

Error Codes & Responses

At Nova Credit, we distinguish between two status message deliveries:

1. Delivered by Nova Credit to the webhook
2. If you call a resource endpoint Nova Credit provides a status in the response

Resource Endpoint Errors

When an error occurs while calling the endpoints the Nova Credit servers send back a JSON object with the following format:

{
  error: "UNKNOWN_CUSTOMER",
  terminated: true,
}

Error Codes

The Nova Credit endpoints return the following HTTP status codes and error messages:

Code	Text	Description
200	-	The request was successful.
400	MALFORMED_HEADERS	The request headers are incorrectly formatted
400	MISSING_INPUT	An input is missing that the endpoint expected
400	INVALID_PUBLIC_ID	The public ID is not valid
401	EXPIRED_TOKEN	The access_token you're sending in the request headers has expired. Please request a new one
403	UNKNOWN_CUSTOMER	The public_id or client_id Nova Credit received in the request from is not recognized. Check your credentials in the Nova Credit Dashboard.
403	UNAUTHORIZED	The client_id and secret_key combination is not recognized. Check your credentials in the Nova Credit Dashboard.
403	ORIGIN_UNAUTHORIZED	The origin of the request is not whitelisted on the Nova Credit servers for CORS
404	INVALID_EXTERNAL_ID	The external ID is not valid
404	INVALID_TOKEN	The public_token or access_token is not valid for reasons other than expiration
408	REQUEST_TIMEOUT	The request timed out
500	INTERNAL_ERROR	Something went wrong. Please send a note to your Nova Credit Representative with additional details so we can investigate

Changelog

We're always working to improve the Nova Credit platform! Here's a snapshot of API features we're shipping and bugs we're squashing.

Changelog History

February 2025

• Fixed bug where identities[].matching.full_name source for an OCROLUS source was missing the source_record_id

December 2024

• Add fraud v3 schema to irregularity_detection
• Add last_statement_end_date to account_details.
• Added source_record_id field to employment and identities node

November 2024

• Add INVALID_PREFILL_* substatuses for ERROR webhooks
• Added external_id to report meta

October 2024

• Fix documentation of income.paystubs[] numeric fields as String not Float

September 2024

• Added EXPIRED status for Webhooks and way to simulate in sandbox

August 2024

• Replaced INVALID_DATE_FORMAT_SUBMITTED with INVALID_PREFILL_DOB in substatus table

August 2024

• Added START_DATE_IS_VALID_DATE, END_DATE_IS_VALID_DATE, PAY_DATE_IS_VALID_DATE, START_DATE_EXISTS, and END_DATE_EXISTS consistency checks

July 2024

• Added instructions on testing the BUREAU_UNRESPONSIVE status
• Added REGENERATED_VISIT webhook eventType
• Added Webhook Signature section
• Added Resistant AI irregularity detection outcomes to Paystub Verification
• Added the new fraud_indication subnode to irregularity_detection
• Added REVIEW as a new potential irregularity_detection status value
• Added annual_salary_rate and estimated_gross_annual_income to payrolls
• Deprecated annual_income on payrolls
• Added gross_total_earnings_amount_current and gross_total_earnings_amount_ytd to payroll statements

June 2024

• Added several values to irregularity_type table that were present in responses but missing from documentation
• Added estimated_net_annual_income and estimated_hire_date fields for payroll reports.

May 2024

• Updating the pay_frequency table to display values using underscores instead of hyphens. (Note: The actual values in the response did not change, the documentation was incorrectly displaying the hyphens)
• Updating the payroll sample response from pay_frequency = weekly to WEEKLY.
• Removed payroll specific substatuses including SOURCE_DATA_FETCH_NOT_SUPPORTED, SOURCE_DATA_FETCH_FAILED, SOURCE_AUTHENTICATION_FAILED.
• Added the error substatus INCOMPLETE_INFORMATION

March 2024

• Added payroll node under income and updated the employment node with employment_type, employment_status, job_title and hire_date

February 2024

• Added a new Finicity sandbox profile that can trigger the SUCCESS webhook status with NO_RECENT_USABLE_INFORMATION substatus.

October 2023

• Added substatus as a field in Visit level webhooks.
• Added COAPPLICANT_GUARANTOR_PROVIDING as a possible substatus for NON_CONTRIBUTING_APPLICANT visits.
• Added INVALID_EXTERNAL_ID and INVALID_PUBLIC_ID errors in Error Codes section.
• Added externalId field to the webhook body.

September 2023

• Added human-readable labels to the product inquiry_types table.

August 2023

• Add field nova_report_revision to the meta section.

March 2023

• Add detect outcomes and scenarios to Paystub Verification.
• Add irregularity_detection to paystubs.

February 2023

• Add explanations to substatus table.

December 2022

• Specify incomes node can be omitted from the report.
• Specify inflows can be omitted from the report.
• Add INVALID_DATE_FORMAT_SUBMITTED to substatus table.

September 2022

• Add attributes to account_details.

July 2022

• Add current_balance, routing_number and full_account_number to account_details.

June 2022

• Add annual_net_income to the insights section under income.

May 2022

• Update usage of NovaConnect widget to Cash Atlas widget.

April 2022

• Update text references of Insight to Cash Atlas in API documentation.
• Update outdated Finicity API link.
• Update API documentation link from https://docs.novacredit.com/voei to https://docs.novacredit.com/cash-atlas.
• Add adverse action codes and descriptions to the adverse_action_codes node.
• Update quickstart guide link from https://demo.novacredit.com/voei-quickstart-guide to https://docs.neednova.com/cash-atlas-quickstart.
• Update usage of /connect/insight to /connect/cash-atlas.
• Remove attributes from account_details subnode.

March 2022

• Update metric_value to be numeric or boolean value.
• Add attributes and adverse_action_codes nodes.

November 2021

• Update usage of /connect/voei to /connect/insight.
• Added NON_CONTRIBUTING_APPLICANT as a new webhook status.

October 2021

• Added oldest_transaction_date as a new field on account_details.

August 2021

• Deprecated support for work email verification.

June 2021

• Added expenses to the report body.

March 2021

• Added heuristics_checks for employment verification.
• Added more detail on visit & supplier logic combinations.

February 2021

• Added sandbox information for work email and paystub verification in Sandbox Mode.

December 2020

• Added responsibility as a new field on account_details.
• Added matched_income as a new field on financial accounts in income.

November 2020

• Added draft versions of employment node and income.paystubs.

October 2020

• Added eventType to the webhook body along with some new body keys and statuses associated with each webhook event type.
• Added substatus to the history object within the webhook body.