Account Monitoring API Reference Beta

Overview

Introduction

Account Monitoring allows you to periodically refresh a consumer's bank data without requiring the consumer to re-authenticate each time. Once a consumer grants long-term consent through the NovaConnect widget, Nova Credit retains access to their bank connections for up to 12 months, enabling you to call the refresh endpoint on-demand to obtain an updated report.

Enablement

Account Monitoring is currently in beta and is supported for Cash Atlas v2 only.

To enable and configure Account Monitoring functionality, please contact your Nova Credit Representative. Our support team will assist you in setting up the necessary configurations to use this functionality.

How It Works

Once Account Monitoring is enabled, the consumer completes the standard NovaConnect widget flow. The consent copy includes Account Monitoring provisions, granting Nova Credit access to the consumer's bank connections for up to 12 months.

This step must be completed once before a refresh can be initiated. After that, multiple refreshes can be initiated without the consumer needing to go through the widget again.

2. Initiating a Refresh

To request a refreshed report, call POST /connect/cash-atlas/v2/refresh with the consumer's identifier. Nova Credit will fetch the latest bank data and generate a new Cash Atlas report. The endpoint returns a new public token for this report.

3. Retrieving a Refreshed Report

Tracking the status of a refreshed report and retrieving it works the same way as a standard Cash Atlas report. Track the status via webhooks or by polling GET /connect/status, and retrieve the report with GET /connect/cash-atlas/v2/json using the public token returned by the refresh endpoint.

4. Revocation

Call POST /connect/consumers/:consumerId/revoke to revoke a consumer's bank connections in the case that the consumer requests it or you no longer need access. Nova Credit will revoke all active connections for that consumer and send a REVOCATION_SUCCEEDED webhook once complete.

5. Re-credentialing

If a consumer's bank connections become unusable or their 12-month consent period expires, the consumer will need to complete the NovaConnect widget flow again to re-establish access. You can tell when this is required by subscribing to the RECREDENTIAL_REQUIRED and CONNECTION_EXPIRING webhooks — see the Webhooks section for details.

OpenAPI Specification

Account Monitoring API documentation is also available as an OpenAPI Specification you can download using the link below.

Download Account Monitoring API OpenAPI Specification version 0.2.0

Endpoints

Base URLs

Environment	Base URL
Production	`https://api.novacredit.com`
Sandbox	`https://api.sandbox.novacredit.com`

POST /connect/cash-atlas/v2/refresh

Initiates a report refresh for a consumer. Returns a publicToken that can be used to track and retrieve the report.

Prerequisites:

Account Monitoring must be enabled for your account
The consumer must have completed the widget flow at least once while Account Monitoring was enabled, to establish consent
The consumer's consent must not have expired or been revoked

Request

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

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	`Bearer <accessToken>` Get an Access Token
`Content-Type`	string	Yes	`application/json`

Body

Field	Type	Required	Description
`consumerId`	string	Yes	Nova Credit's unique identifier for the consumer (UUID)
`productId`	string	Yes	The Cash Atlas v2 product to generate the report for

Example:

{
	"consumerId": "b281e335-9d19-4aa7-b559-e74d08a05cf4",
	"productId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Response

A response with a 202 status indicates that the refresh has been initiated. Standard VISIT webhooks will be sent to indicate the status of the report.

Body

Field	Type	Description
`publicToken`	string	Public token for this new report, can be used to retrieve the report once completed

Example:

{
	"publicToken": "7a3f1c84-92b4-4d7e-a903-1c8e5b6f2d01"
}

Error Responses

HTTP Status	Error	Description
`400`	`MALFORMED_BODY`	Missing or invalid request body
`403`	`CONSENT_NOT_PROVIDED`	The consumer did not consent to Account Monitoring functionality
`403`	`UNAUTHORIZED`	Invalid or missing access token
`403`	`FEATURE_NOT_ENABLED`	Account Monitoring is not enabled for your account
`404`	`INVALID_CONSUMER_ID`	No consumer found for the provided `consumerId`
`404`	`INVALID_PRODUCT`	No product found for the provided `productId`, or it does not reference a Cash Atlas v2 product
`404`	`INVALID_TOKEN`	Malformed access token
`500`	`INTERNAL_ERROR`	Unexpected server error

If the consumer's access has expired, the refresh will result in a RECREDENTIAL_REQUIRED webhook rather than a synchronous error — see Webhooks for details.

POST /connect/consumers/:consumerId/revoke

Revokes access to a consumer's bank connections. A REVOCATION_SUCCEEDED webhook will be sent once revocation completes.

Request

POST https://api.novacredit.com/connect/consumers/:consumerId/revoke

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Basic Auth, containing the base-64 encoded string of your `client_id:secret_key`

Path Parameters

Parameter	Type	Required	Description
`consumerId`	string	Yes	Nova Credit's unique identifier for the consumer (UUID)

Response

A response with a 202 status indicates that revocation has been initiated. The REVOCATION_SUCCEEDED webhook is sent once all supplier-side connections have been deleted.

Body

The response body has no content.

Error Responses

HTTP Status	Error	Description
`400`	`BAD_REQUEST`	Input format is invalid
`403`	`UNKNOWN_CUSTOMER`	Invalid or missing credentials
`403`	`FEATURE_NOT_ENABLED`	Account Monitoring is not enabled for your account
`404`	`INVALID_CONSUMER_ID`	No consumer found for the provided `consumerId`
`500`	`INTERNAL_ERROR`	Unexpected server error

Webhooks

Account Monitoring introduces a new webhook event type, CONSUMER_CONNECTION, with four new event statuses. Subscribe to these in the Developer tab of the Nova Credit Dashboard alongside your existing webhook subscriptions.

Nova Credit makes a POST request to your configured callback URL when one of these events occurs.

Webhook Statuses

Status	Description
`CONNECTION_EXPIRING`	The consumer's consent window or bank connection is approaching expiration. Sent 14 days and again 7 days before expiry
`RECREDENTIAL_REQUIRED`	One or more of the consumer's connections became unusable (e.g. the consumer revoked access at their bank, or consent has expired). The consumer must re-authenticate through the NovaConnect widget
`REVOCATION_FAILED`	An attempt to revoke the consumer's connections failed. Includes the number of retry attempts remaining
`REVOCATION_SUCCEEDED`	The consumer's connections have been successfully revoked

CONNECTION_EXPIRING

Sent proactively when a consumer's consent is approaching expiration. Nova Credit sends this event twice: once 14 days before expiry and once 7 days before expiry. This is driven by Nova Credit's consent window, not by any expirations that might be in place on the financial institution's end.

Use this event to invite the consumer to complete the NovaConnect widget flow again before the connection lapses, avoiding any interruption to refresh functionality.

Webhook Body

Field	Type	Description
`eventId`	string	Unique ID for this webhook event
`eventCreatedTime`	string	ISO 8601 timestamp of when the event was created
`consumerId`	string	Nova Credit's unique identifier for the consumer
`consumerExternalId`	string	Your system's identifier for the consumer. Omitted if not set
`eventType`	string	Always `CONSUMER_CONNECTION`
`status`	string	Always `CONNECTION_EXPIRING`
`consentExpiresAt`	string	ISO 8601 timestamp indicating when the consumer's consent will expire

Example:

{
	"eventId": "a7e3b921-5cd8-4f2e-8b03-6d9a0c1e7f45",
	"eventCreatedTime": "2027-03-01T00:00:00.00Z",
	"consumerId": "b281e335-9d19-4aa7-b559-e74d08a05cf4",
	"consumerExternalId": "472cbdc9-cf31-4117-a095-e27e2db054e5",
	"eventType": "CONSUMER_CONNECTION",
	"status": "CONNECTION_EXPIRING",
	"consentExpiresAt": "2027-04-01T00:00:00.00Z"
}

RECREDENTIAL_REQUIRED

Sent when Nova Credit detects that one or more of the consumer's connections are no longer usable — for example, if the consumer revoked access at their financial institution.

A refreshed report may still be successfully generated if the consumer has additional connections that are still active. The data in the report will be determined based only on the active connections. If there are no active connections, a refreshed report will terminate with a NOT_AUTHENTICATED status.

The consumer must complete the NovaConnect widget flow again to re-establish their connections.

Webhook Body

Field	Type	Description
`eventId`	string	Unique ID for this webhook event
`eventCreatedTime`	string	ISO 8601 timestamp of when the event was created
`consumerId`	string	Nova Credit's unique identifier for the consumer
`consumerExternalId`	string	Your system's identifier for the consumer. Omitted if not set
`eventType`	string	Always `CONSUMER_CONNECTION`
`status`	string	Always `RECREDENTIAL_REQUIRED`
`publicToken`	string	The public token for the refresh that encountered the authentication failure, if applicable

Example:

{
	"eventId": "9c4d2a81-1bf3-4e9c-b702-5a6f7c9e0b34",
	"eventCreatedTime": "2026-04-15T09:10:00.00Z",
	"consumerId": "b281e335-9d19-4aa7-b559-e74d08a05cf4",
	"consumerExternalId": "472cbdc9-cf31-4117-a095-e27e2db054e5",
	"eventType": "CONSUMER_CONNECTION",
	"status": "RECREDENTIAL_REQUIRED",
	"publicToken": "7a3f1c84-92b4-4d7e-a903-1c8e5b6f2d01"
}

REVOCATION_FAILED

Sent when an attempt to revoke the consumer's connections fails. Nova Credit will retry automatically; this event is sent after each failed attempt.

Webhook Body

Field	Type	Description
`eventId`	string	Unique ID for this webhook event
`eventCreatedTime`	string	ISO 8601 timestamp of when the event was created
`consumerId`	string	Nova Credit's unique identifier for the consumer
`consumerExternalId`	string	Your system's identifier for the consumer. Omitted if not set
`eventType`	string	Always `CONSUMER_CONNECTION`
`status`	string	Always `REVOCATION_FAILED`
`attemptsRemaining`	integer	Number of retry attempts remaining before revocation gives up

Example:

{
	"eventId": "c2d4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
	"eventCreatedTime": "2026-04-01T15:00:00.00Z",
	"consumerId": "b281e335-9d19-4aa7-b559-e74d08a05cf4",
	"consumerExternalId": "472cbdc9-cf31-4117-a095-e27e2db054e5",
	"eventType": "CONSUMER_CONNECTION",
	"status": "REVOCATION_FAILED",
	"attemptsRemaining": 2
}

REVOCATION_SUCCEEDED

Sent after the consumer's connections have been successfully revoked.

Webhook Body

Field	Type	Description
`eventId`	string	Unique ID for this webhook event
`eventCreatedTime`	string	ISO 8601 timestamp of when the event was created
`consumerId`	string	Nova Credit's unique identifier for the consumer
`consumerExternalId`	string	Your system's identifier for the consumer. Omitted if not set
`eventType`	string	Always `CONSUMER_CONNECTION`
`status`	string	Always `REVOCATION_SUCCEEDED`

Example:

{
	"eventId": "3f9a1b72-8de4-4c7a-9f01-2c5e6b8d4a12",
	"eventCreatedTime": "2026-04-01T14:22:00.00Z",
	"consumerId": "b281e335-9d19-4aa7-b559-e74d08a05cf4",
	"consumerExternalId": "472cbdc9-cf31-4117-a095-e27e2db054e5",
	"eventType": "CONSUMER_CONNECTION",
	"status": "REVOCATION_SUCCEEDED"
}

Changelog

May 2026

POST /connect/consumers/:consumerId/revoke documentation updated to use Basic auth

April 2026

Initial documentation ahead of beta feature readiness
- Includes endpoints:
  - POST /connect/account-monitoring/refresh
  - POST /connect/account-monitoring/revoke
- Includes webhooks:
  - CONNECTION_EXPIRING
  - RECREDENTIAL_REQUIRED
  - REVOCATION_FAILED
  - REVOCATION_SUCCEEDED

Overview​

Introduction​

Enablement​

How It Works​

1. Initial Widget Report​

2. Initiating a Refresh​

3. Retrieving a Refreshed Report​

4. Revocation​

5. Re-credentialing​

OpenAPI Specification​

Endpoints​

Base URLs​

POST /connect/cash-atlas/v2/refresh​

Request​

Response​

Error Responses​

POST /connect/consumers/:consumerId/revoke​

Request​

Response​

Error Responses​

Webhooks​

Webhook Statuses​

CONNECTION_EXPIRING​

Webhook Body​

RECREDENTIAL_REQUIRED​

Webhook Body​

REVOCATION_FAILED​

Webhook Body​

REVOCATION_SUCCEEDED​

Webhook Body​

Changelog​

May 2026

April 2026

Overview

Introduction

Enablement

How It Works

1. Initial Widget Report

2. Initiating a Refresh

3. Retrieving a Refreshed Report

4. Revocation

5. Re-credentialing

OpenAPI Specification

Endpoints

Base URLs

POST /connect/cash-atlas/v2/refresh

Request

Response

Error Responses

POST /connect/consumers/:consumerId/revoke

Request

Response

Error Responses

Webhooks

Webhook Statuses

CONNECTION_EXPIRING

Webhook Body

RECREDENTIAL_REQUIRED

Webhook Body

REVOCATION_FAILED

Webhook Body

REVOCATION_SUCCEEDED

Webhook Body

Changelog