Skip to main content

Multi-Product Token Quickstart Guide

Nova Credit provides a "Multi-Product Token" feature, which allows customers to generate a secondary report from an existing report when the underlying source data is compatible for both reports.

This document provides information on how to interact with the Nova Credit API to generate a secondary report using the Multi-Product Token functionality. For more general information about the Nova Credit APIs, view your corresponding quickstart guide.

Where to configure Multi-Product Token Beta​

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

Supported Versions

Source ReportSecondary Report
Cash Atlas v1Income Navigator v2
Cash Atlas v2Income Navigator v2
Income Navigator v2Cash Atlas v2

Credentials & Identifiers​

Account Keys​

These values are accessible from your Nova Credit Dashboard.

  • clientId [string] Your Nova Credit API identifier. You will use this to programmatically access resources.
  • secretKey [string] Your Nova Credit API key (keep this secret). You will use this to programmatically access resources.
  • productId [string] Configured Products will be associated to a Nova Product type. When creating a multi-product token, use a productId that is associated with the type of report you want to create.

Programmatically generated tokens​

  • publicToken [string] Identifies a specific report.
  • multiProductToken [string] Identifies a report generated from another report's source data. A multiProductToken is a publicToken.
  • accessToken [string] Used to authorize server-side requests (keep this secret). You will generate an accessToken each time you fetch a report.

Generate a multi-product token​

The following instructions apply after an original source report has already been created for an applicant.

To generate the secondary report, create a multi-product token by using the POST https://api.novacredit.com/connect/multi-product-tokens endpoint. This will initialize generating a secondary report that is associated with the returned multiProductToken. This multiProductToken can be used as a publicToken with the rest of the API.

Required headers‍

  • Authorization Basic Auth, containing the base-64 encoded string of your clientId:secretKey.
  • Content-Type application/json.

Required body parameters

  • publicToken [string] Identifier of the original report to use as the source of data for the multi-product token report.
  • productId [string] ID of the product to be used for the multi-product token. This must be a different product from what was used for the original report.

Optional body parameters

  • userArgs [string] To set additional metadata into the user args field on the multi-product token report.
  • externalId [string] To set an external id on the multi-product token report. An external id must be unique and cannot be re-used across multiple reports, including multi-product tokens. This external id MUST NOT include any consumer PII.

Possible responses‍‍

  • 200 (OK) The newly generated multiProductToken is returned. This can be used to access the secondary report once it is ready.
  • 400 (Bad Request) Invalid request, malformed or missing required inputs, or an invalid source report or product configuration. Error will be one of INVALID_PARAMETERS, MALFORMED_BODY, MALFORMED_HEADERS, INVALID_STATE.
  • 403 (Forbidden) Unauthorized request. Your clientId or secretKey was incorrect, or you did not correctly base-64 encode it.
  • 404 (Not Found) A required element could not be found, such as the publicToken, or the productId. Error will be one of INVALID_TOKEN, INVALID_PRODUCT.

Usage Constraints

  • Multi-product tokens must be generated within 30 days from the creation of the initial report.
  • The source report must have been created from bank data.
  • A multi-product token report may not be used as the subsequent source for another new multi-product token.
  • Consumer information provided for the source report must have included firstName, lastName, email, dob, as well as state.
  • The income model suite being run must be at least version 1.2.

Example request

curl --location --request POST 'https://api.novacredit.com/connect/multi-product-tokens' \
--header 'Authorization: Basic {base64(clientId:secret)}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"productId": "d0e9bed3-33aa-4460-a868-22b333ce2227",
	"publicToken": "da31c5d3-115f-43e3-8f19-c9a4484a943a"
}'

Example response

{
	"multiProductToken": "9055c0c4-1f77-4f80-afac-35ea02f84020"
}

Accessing the secondary report​

There are two options to verify the secondary report is ready to be retrieved.

Recommended option: using webhooks

All created multi-product tokens will result in a VISIT SUCCESS webhook call to the registered callback URL. The webhook payload will contain the multi-product token in the publicToken field, and is an indication that the report is ready to be retrieved.

More information regarding webhooks can be found in the API docs:

Alternative option: using the /status endpoint

If you are unable to subscribe to webhooks, you will need to get an access token, then pass the multi-product token to the status endpoint and poll for the status of the report to determine when it is ready.

More information can be found in the quickstart guides:

Note that the access token and status endpoints are not specific to Cash Atlas or Income Navigator, and can both be used for either case.

Once the report is ready

The multi-product token report can be retrieved using our standard get report endpoints, by using the multi-product token as the publicToken, or by using an external id provided during the multi-product token creation.

More information can be found in the quickstart guides: