Cash Atlas BYO Data API Reference

The BYO Data API for Cash Atlas v2 is a new feature that is currently in beta. If you are interested in trying it out, please reach out to your Nova Credit representative for more details.

API Overview Beta

Introduction

The Cash Atlas Bring Your Own (BYO) endpoint flow lets you directly access our state-of-the-art cashflow insights using your first-party consumer banking data.

The data flow is as such:

1. Configure a product in the Nova Credit customer dashboard. This will give you product IDs you can use to group your reports.
2. Configure webhook subscriptions in the Nova Credit customer dashboard. These will provide updates as the reports are created for each request.
3. Get an access token from our API.
4. Submit your consumer banking data to our API to generate a Cash Atlas report.
5. Wait for a visit webhook indicating completion or poll our status endpoint until the report status is SUCCESS.
6. Get the report from our API.

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.

Base URL for API Endpoints

Please note, this is the base URL for all BYO API endpoints:

• https://cash-api.novacredit.com/

Authentication

Our Cash Atlas BYO API uses a Bearer Token authentication scheme. We provide you with a client_id and secret_key via the Nova Credit customer dashboard. You can then use our access token endpoint to generate and retrieve a short-lived access token. Once your access token has expired, simply repeat the access token flow to get a new one.

Access Tokens

Access tokens are generated using the Access Token endpoint GET https://cash-api.novacredit.com/connect/accesstoken

Each token will be valid for 5 minutes. Nova strongly recommends re-using tokens for submitting requests and retrieving responses while they are valid.

Generating a new token for every API request is not recommended.

Endpoints

Get Access Token

Description: This endpoint allows you to generate a short-lived access token that can be used to access our API. The token will have a TTL of 5 minutes.

GET https://cash-api.novacredit.com/connect/accesstoken

Headers:

• X-ENVIRONMENT: Environment you want to target (production or sandbox)

Authentication: Basic Auth

• username: {{client_id}}
• password: {{secret_key}}

Existing documentation: Cash Atlas v2 Quickstart - Get Access Token

Response Example:

{
	"accessToken": "{{accesstoken}}",
	"exp": 1526077901
}

Possible Responses:

• 200 OK: Success
• 403 Forbidden: Unauthorized or Unknown Customer

Generate Cashflow Underwriting Report

Description: Start generating a CFUW report using your first-party consumer banking data.

POST https://cash-api.novacredit.com/connect/v2/cash-atlas/byo-report

Headers:

• Authorization: Bearer token (e.g., 'Bearer ' + base64('your-access-token'))
• X-ENVIRONMENT: Environment you want to target (production or sandbox)
• X-PRODUCT-ID: Nova Credit product ID to associate with this report

Request Body:

{
	"userArgs": "additional-args",
	"externalId": "your-unique-external-id",
	"pullDate": "2024-04-07T11:22:33.456Z",
	"personal": {
		"firstName": "John",
		"lastName": "Doe",
		"dob": "1985-06-15",
		"email": "john.doe@example.com",
		"phone": "555-123-4567"
	},
	"address": {
		"street": "123 Main St",
		"city": "San Francisco",
		"state": "CA",
		"postalCode": "94105"
	},
	"accounts": [
		{
			"id": "BAID-2393939",
			"institutionName": "Chase",
			"accountType": "CHECKING",
			"currentBalance": 1234.54,
			"dateBalanceLastUpdated": "2024-06-14T12:23:44.456Z",
			"dateAccountOpened": "2022-04-10T09:24:44.456Z",
			"currency": "USD",
			"transactions": [
				{
					"id": "TID-2393939",
					"status": "POSTED",
					"datePosted": "2024-06-14T12:23:44.456Z",
					"amount": -123.44,
					"description": "AppleBees #409 xxxxxxxxxxxxxx4566",
					"merchant": "AppleBees",
					"memo": "Dinner with friends",
					"creditOrDebit": "DEBIT"
				},
				{
					"id": "TID-2393940",
					"status": "POSTED",
					"datePosted": "2024-06-15T00:00:00.000Z",
					"amount": 1500.15,
					"description": "PAYMENTS WALMART ACH CREDIT",
					"creditOrDebit": "CREDIT"
				}
			]
		}
	]
}

Note: externalId must be unique per request. Duplicate external IDs will result in a 400 Bad Request response.

Response Example:

{
	"publicToken": "{{reportPublicToken}}",
	"externalId": "{{reportExternalId}}",
	"userArgs": "{{userArgs}}",
	"status": "PENDING"
}

Possible Responses:

• 200 OK: Success
• 400 Bad Request: Malformed Body
• 401 Unauthorized: Expired Token
• 403 Forbidden: Unauthorized

Get Cashflow Underwriting Report Status

Note: Polling for report status is supported, but not recommended. Nova Credit highly recommends configuring webhook subscriptions through the customer dashboard.

Description: Check the status of your Cashflow Underwriting report.

GET https://cash-api.novacredit.com/connect/status

Headers:

• Authorization: Bearer token (e.g., 'Bearer ' + base64('your-access-token'))
• X-ENVIRONMENT: Environment you want to target (production or sandbox)
• X-EXTERNAL-ID: External ID of the CashAtlas report you are retrieving (required if no X-PUBLIC-TOKEN header is provided)
• X-PUBLIC-TOKEN: Unique identifier of the CashAtlas report you are retrieving (required if no X-EXTERNAL-ID header is provided)

Response Example:

{
	"status": "PENDING",
	"substatus": null
}

Possible Responses:

• 200 OK: Status retrieved
• 404 Not Found: Invalid Token
• 401 Unauthorized: Expired Token
• 403 Forbidden: Unauthorized

Retrieve Cashflow Underwriting Report

Description: Retrieve the completed CFUW report.

GET https://cash-api.novacredit.com/connect/cash-atlas/v2/json

Headers:

• Authorization: Bearer token (e.g., 'Bearer ' + base64('your-access-token'))
• X-ENVIRONMENT: Environment you want to target (production or sandbox)
• X-EXTERNAL-ID: External ID of the CashAtlas you are retrieving (required if no X-PUBLIC-TOKEN header is provided)
• X-PUBLIC-TOKEN: Unique identifier of the CashAtlas report you are retrieving (required if no X-EXTERNAL-ID header is provided)

Existing documentation: Cash Atlas v2 Report Schema

Response Example:

{
	"meta": {
		"user_args": "{{userArgs}}",
		"created_at": "2024-04-07T00:53:43.829Z",
		"api_version": "2.0.0",
		"public_token": "{{reportPublicToken}}"
	},
	"product": {
		"product_id": "c3a37c41-7c62-11e7-8141-19157d9a48c7",
		"name": "Home Community FCU",
		"inquiry_type": "LENDING"
	},
	"sources": [
		{
			"source_id": "CUSTOMER_INPUT",
			"source_type": "CUSTOMER_INPUT",
			"status": "SUCCESS"
		}
	],
	"identity": [
		{
			"source_id": "CONSUMER_INPUT",
			"first_name": "John",
			"last_name": "Doe",
			"full_name": "John Doe",
			"emails": ["john.doe@example.com"]
		}
	],
	"account_details": [
		{
			"source_id": "CUSTOMER_INPUT",
			"months_available": 6,
			"account_id": "36139831-0a91-4d1f-bc3e-edc908a978c6",
			"institution_name": "CHASE",
			"account_name": "Chase Checking",
			"account_type": "CHECKING",
			"date_opened": "2015-05-01",
			"truncated_account_number": "1234",
			"current_balance": 45971
		}
	],
	"attributes": [
		{
			"name": "ASSETS_CASH_EQUIVALENT_BALANCE_CURRENT",
			"description": "Current cash equivalent balance of assets",
			"node": "ASSET",
			"source_ids": ["CUSTOMER_INPUT"],
			"adverse_action_code": "21",
			"value": 45971
		},
		{
			"name": "TOTAL_INFLOW_SUM",
			"description": "Sum of total inflow over the entire history",
			"node": "TOTAL",
			"source_ids": ["CUSTOMER_INPUT"],
			"adverse_action_code": "32",
			"value": 1500.15
		}
	],
	"scores": [
		{
			"source_ids": ["CUSTOMER_INPUT"],
			"score_type": "NOVA_SCORE_CASH_FLOW",
			"score_version": "v1.0",
			"value": 600,
			"adverse_action_codes": [
				{
					"code": "21",
					"description": "Cash equivalent account balance is too low"
				}
			]
		}
	]
}

Possible Responses:

• 200 OK: Success
• 404 Not Found: Invalid Token
• 401 Unauthorized: Expired Token
• 403 Forbidden: Unauthorized

Data Requirements

Input Fields

The following table describes the fields that can be passed as a part of the request. All fields are optional unless labeled “Required” under the Constraints column.

Field	Type	Description	Required	Constraints
userArgs	String	Additional arguments for user.	Optional	Length: 1-255 characters
externalId	String	A unique identifier for the user.	Optional, Preferred	Length: 1-64 characters, Must be unique per request
pullDate	DateTime	The date when the consumer's banking data (accounts, transactions, etc) was last obtained or updated from your data supplier.	Required	Format ISO 8601: YYYY-MM-DDTHH:mm:ss.SSSZ, Must be a current or past date within the last 30 days, and be greater than or equal to all accounts[].dateBalanceLastUpdated and accounts[].transactions[].datePosted.
applicationDate	DateTime	The date the application was submitted.	Optional	Format ISO 8601: YYYY-MM-DDTHH:mm:ss.SSSZ, Must be a past or current date
personal.firstName	String	The first name of the consumer.	Required	Length: 1-50 characters, Acceptable characters are alphabetic (including unicode characters such as ñ), as well as apostrophes, hyphens, or periods.
personal.lastName	String	The last name of the consumer.	Required	Length: 1-50 characters. Acceptable characters are alphabetic (including unicode characters such as ñ), as well as apostrophes, hyphens, or periods.
personal.dob	Date	The date of birth of the consumer.	Optional	Format: YYYY-MM-DD, Must be a past date. See PII Requirements below
personal.email	String	The email address of the consumer.	Required	Valid email format, Length: max 100 characters
personal.phone	String	The consumer's US phone number.	Optional	Format: XXX-XXX-XXXX, Numeric only
address.street	String	The street address of the consumer.	Optional	Length: 1-100 characters. See PII Requirements below
address.city	String	The city where the consumer resides.	Optional	Length: 1-100 characters, Alphabetic and spaces only. See PII Requirements below
address.state	String	The state code where the consumer resides.	Optional	2-letter state code (US states + DC), Uppercase. See PII Requirements below
address.postalCode	String	The postal (zip) code of the consumer's address.	Optional	Length: 5-10 characters, Numeric only. See PII Requirements below
accounts[].id	String	A unique identifier for the account.	Required	Length: 1-50 characters, Alphanumeric; Must be unique within the accounts list.
accounts[].institutionName	String	The name of the financial institution.	Required	Length: 1-100 characters
accounts[].accountType	String	The type of account.	Required	Enum: Only SAVINGS & CHECKING allowed
accounts[].currentBalance	Decimal	The current balance of the account.	Required	Precision: 2 decimal places 0 is an acceptable value, if the current balance of the account is known to be 0. 0 should not be used as a default if the current balance is unknown.
accounts[].dateBalanceLastUpdated	DateTime	The timestamp when the current balance was last updated. This must be provided by the underlying financial institution.	Optional	Format ISO 8601: YYYY-MM-DDTHH:mm:ss.SSSZ, Must be a past or current date
accounts[].dateAccountOpened	DateTime	The date and time when the account was opened.	Optional	Format ISO 8601: YYYY-MM-DDTHH:mm:ss.SSSZ, Must be a past date/time
accounts[].currency	String	The currency of the account.	Required	3-letter currency code (ISO 4217)
accounts[].transactions[].id	String	A unique identifier for the transaction.	Required	Length: 1-50 characters, Alphanumeric; Must be unique within the account.
accounts[].transactions[].status	String	The status of the transaction.	Required	Enum: PENDING or POSTED
accounts[].transactions[].datePosted	DateTime	The date and time when the transaction was posted.	Required	for transactions with POSTED status; Format ISO 8601: YYYY-MM-DDTHH:mm:ss.SSSZ, Must be a past or current date/time
accounts[].transactions[].amount	Decimal	The amount of the transaction.	Required	Precision: 2 decimal places
accounts[].transactions[].description	String	The description of the transaction.	Required	Length: 1-255 characters
accounts[].transactions[].merchant	String	The name of the merchant where the transaction occurred.	Optional	Length: 1-100 characters, Alphanumeric
accounts[].transactions[].memo	String	Additional notes about the transaction.	Optional	Length: 0-255 characters
accounts[].transactions[].creditOrDebit	String	Indicates if the transaction is a credit or debit. Money flowing into the account should be marked as CREDIT, and money flowing out of the account should be marked as DEBIT.	Required	Enum: CREDIT or DEBIT

PII Requirements

Cash Atlas products require some consumer PII in order to successfully generate reports.

The following fields are always required:

• firstName
• lastName
• email

One of the following is required:

• dob
• Full Address:
  • street ⁽¹⁾
  • city
  • state
  • postalCode

We recommend sending full address rather than DOB due to it being less sensitive user data.

⁽¹⁾ Nova accepts one line street addresses, so any additional street address information should be added here.

For example:

{
	"address": {
		"street": "345 Polk St. Apt 6B",
		"city": "San Francisco",
		"state": "CA",
		"postalCode": "94105"
	}
}

Possible Status and Substatus Values

See: Cash Atlas v2 Substatus

Status

Status	Description
PENDING	Report generation is in progress
SUCCESS	Report generation succeeded
ERROR	Report generation failed

Substatus

All substatuses will result from validations

Status	Description
INVALID_PREFILLS_PII_MISSING	Must provide firstName, lastName, email, and DOB or full address.
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, apostrophes 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, apostrophes and dashes.
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 be a string with a valid USA zip code.

Rate Limiting

In order to maintain system stability across the board for Nova customers, Nova enforces rate limiting for incoming requests by customers. Exceeding the endpoint rate limit will result in an error response with a status code of 429: Too Many Requests.

The rate limit for the POST https://cash-api.novacredit.com/connect/v2/cash-atlas/byo-report endpoint is: 30 requests per minute

These endpoints do not strictly enforce the same rate limit.

• Access Token: GET https://cash-api.novacredit.com/connect/accesstoken
• Report Status: GET https://cash-api.novacredit.com/connect/status
• Retrieve Report: GET https://cash-api.novacredit.com/connect/cash-atlas/v2/json

However, exceeding 30 requests per minute for these endpoints is not recommended. Calls to these endpoints will not impact the rate limiting that is in place for the submit report request endpoint.

In order to request an increase for the rate limit configuration, please contact the Nova support team.

Sandbox Environment

The Cash Atlas sandbox environment provides a safe testing space to integrate and validate your implementation before going to production. This guide covers everything you need to know about testing in sandbox mode.

Overview

The sandbox environment allows you to:

• Access predefined test user profiles with different data scenarios
• Simulate various response states and error conditions

Accessing Sandbox Reports

To retrieve a sandbox report, you must provide specific test user information when submitting a request to the /byo-report endpoint with X-ENVIRONMENT set to sandbox. The required information must match one of our predefined test profiles exactly.

Required Information

Each test user requires the following field:

• personal.firstName - The test user's first name

However, to ensure consistency with our production requirements, we recommend also passing in the following as part of your testing:

• personal.lastName - The test user's last name
• personal.dob - Date of birth in YYYY-MM-DD format
• personal.email - The test user's email address

For sandbox testing, any address value can be passed into the address field.

Learn more about the /byo-request endpoint data requirements in the Data Requirements section.

Test User Profiles

We provide five test user profiles, each designed to simulate different financial scenarios and scores:

Profile Type	First Name	Last Name	Date of Birth	Email	Scenario	Score Value
Default User	Raymond	Marshal	1995-10-01	raymond@email.com	Complete financial profile with typical transaction history	685
Single Primary Account	Sarah	Single	1986-11-12	sarah@email.com	Single checking account with standard transactions	577
Multi-Account	Mike	Many	1992-06-08	mike@email.com	Multiple accounts (checking, savings, investment)	749
Joint Account	Jason	Joint	1976-04-09	jason@email.com	Joint account ownership with shared responsibility	754
No Income	Nolan	NoTransactions	1992-04-07	nolan@email.com	Account with no transaction history	null

Simulating Error States

You can trigger specific error conditions by using special values in the personal.lastName field:

Error

• Last Name error
• Result: Triggers an ERROR status
• Use Case: Test error handling in your integration

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

December 2025

• Updated sandbox user Raymond's last name to from "Ricard" to "Marshal".

November 2025

• Added constraint that pullDate must be greater than or equal to all accounts[].dateBalanceLastUpdated and accounts[].transactions[].datePosted dates.
• Added constraint that pullDate must be at least 30 days recent to when the BYO request was invoked.

September 2025

• Added Sandbox Environment section.

May 2025

• Added pullDate as a required input. Moved applicationDate to an optional input.

March 2025

• Added Beta note to BYO API documentation
• Transferred BYO API documentation from internal docs to Nova public documentation with formatting changes