Skip to main content

Parent Relay Token Guide

Nova Credit provides a "Parent Relay Token" feature that allows parent customers to retrieve a consumer's existing income report for a new product without requiring the consumer to re-authenticate.

This document provides information on how to interact with the Nova Credit API using the Parent Relay Token feature. For more general information about the Nova Credit APIs, view your corresponding quickstart guide: (Credit Passport Quickstart, Income Navigator Quickstart, Cash Atlas Quickstart).

Where to configure Parent Relay Token​

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

Prerequisites​

The consumer must be registered with Nova Credit before calling this endpoint. Use the POST /consumers endpoint to register a consumer and obtain a consumer_id.

Credentials & Identifiers​

Account Keys​

The NovaConnect and server-side API keys are accessible from your Nova Credit Dashboard.

  • publicId [string] Used to identify your account.
  • 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.

Programmatically generated tokens​

  • parentRelayToken [string] UUID returned by this endpoint identifying the downstream visit. A parentRelayToken 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.

Forward an existing report​

Call POST https://api.novacredit.com/connect/parent-relay-tokens to check whether an eligible report exists for a consumer and, if so, begin generating a new downstream report from the original data.

Always check reportAvailable in the response before proceeding. A 200 status indicates the request was valid and processed — it does not guarantee a report was found.

Required headers

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

Required body parameters

  • consumerId [string] UUID of the registered consumer.
  • productId [string] UUID of the product to generate the new report against.

Response fields

FieldTypeDescription
reportAvailablebooleantrue if an eligible report was found and a downstream visit was created. false if no eligible report exists or the consumer has revoked access.
parentRelayTokenstring | nullUUID of the downstream visit. Use this as the publicToken to retrieve the report. null when reportAvailable is false.
consumerIdstring | nullThe consumerId provided in the request.
productIdstring | nullThe productId provided in the request.
reportDatestring | nullISO 8601 timestamp of when the original report was completed. null when reportAvailable is false. You can use this value to apply your own freshness policy before deciding whether to proceed with retrieval.
reportSourceTypestring | nullThe data source type of the original report. One of BANK_TRANSACTION, EMPLOYMENT, or PAYROLL. null when reportAvailable is false.
reportStatusstring | nullStatus of the original report. SUCCESS when reportAvailable is true. null otherwise.
reportSubstatusstring | nullSubstatus of the original report. null when reportAvailable is true.

Possible responses

StatusDescription
200 OKRequest was processed. Check reportAvailable in the response body to determine whether a report was found.
400 Bad RequestMalformed or invalid request, headers, or missing required parameters. Error will be one of INVALID_PARAMETERS, MALFORMED_BODY, MALFORMED_HEADERS.
403 ForbiddenUnauthorized request. Your clientId or secretKey was incorrect, you did not correctly base-64 encode it, or the Parent Relay Token feature is not enabled for your parent account.
404 Not FoundThe productId provided does not belong to a customer under your parent account.

Eligibility criteria

An existing report is eligible as the source for a parent relay token if all of the following are true:

  • The existing report has a status of SUCCESS with no substatus.
  • The existing report was generated within the last 30 days.
  • The existing report's novaProductType matches that of the requested productId.
  • The existing report's data source type is compatible with the workflow configured for the requested productId.
  • The existing report belongs to a customer under the same parent as the caller.
  • The existing report was not itself generated from a parent relay token.
  • The consumer has not revoked parent relay token access.

If multiple reports satisfy all criteria, the most recently completed report is used.

note

The downstream report reflects the configuration of the upstream product at the time the original report was generated, not the current configuration of the target product. If configurations that affect report output have changed within the last 30 days, the downstream report may not exactly match what a fresh report against the target product would return. The Nova product type (Income Navigator, Cash Atlas, etc.) is guaranteed to be consistent.

Example request

curl --location --request POST 'https://api.novacredit.com/connect/parent-relay-tokens' \
--header 'Authorization: Basic {base64(clientId:secretKey)}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "consumerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productId": "d0e9bed3-33aa-4460-a868-22b333ce2227"
}'

Example response — report available

{
	"consumerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
	"parentRelayToken": "9055c0c4-1f77-4f80-afac-35ea02f84020",
	"productId": "d0e9bed3-33aa-4460-a868-22b333ce2227",
	"reportAvailable": true,
	"reportDate": "2026-10-15T14:23:00.000Z",
	"reportSourceType": "EMPLOYMENT",
	"reportStatus": "SUCCESS",
	"reportSubstatus": null
}

Example response — no report available

{
	"consumerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
	"parentRelayToken": null,
	"productId": "d0e9bed3-33aa-4460-a868-22b333ce2227",
	"reportAvailable": false,
	"reportDate": null,
	"reportSourceType": null,
	"reportStatus": null,
	"reportSubstatus": null
}

Retrieve the report​

When reportAvailable is true, the downstream report is generated asynchronously from the original source data. All subsequent steps — checking status and retrieving the report — are performed by the parent using the same clientId and secretKey used to call the endpoint above.

Step 1 — Verify the report is ready​

There are two options for knowing when the report is ready to be retrieved. Because report generation typically completes in a couple of seconds, polling the /status endpoint is a straightforward and valid approach.

Option 1: using the /status endpoint

Obtain an access token (see Step 2 below) and poll GET /connect/status with the parentRelayToken as the X-PUBLIC-TOKEN header until the status is SUCCESS.

Option 2: using webhooks

When a parent relay token is created, two webhook events are sent to the callback URL registered for the downstream child account:

  1. VISIT PENDING — sent immediately when the parent relay token is created. This signals that report generation has begun.
  2. VISIT SUCCESS — sent when report generation completes and the report is ready to retrieve.

The webhook payload for both events contains the parentRelayToken value in the publicToken field.

More information regarding the webhook body can be found in the API docs:

Step 2 — Get an access token​

See Income Navigator Quickstart Guide — Get an access token.

Step 3 — Retrieve the report​

Once the report status is SUCCESS, retrieve it using the standard report endpoint with the parentRelayToken as the X-PUBLIC-TOKEN header. The full integration steps can be found in the quickstart guide:

Report timestamps​

Reports generated via the Parent Relay Token feature include an additional meta.relay_token_created_at field containing the date the parent relay token was generated.

meta.created_at retains its standard meaning — the date the original consumer data was retrieved from the data supplier — and is not affected by parent relay token generation.

Consumer notification​

When a report is retrieved using a parent relay token, the consumer is automatically notified by email that their report was shared. This notification is sent upon report retrieval, not at the time the parent relay token is generated. If the token is generated but never used, no notification is sent.

Consumer access revocation​

Consumers may revoke their consent for parent relay token report sharing at any time by contacting Nova Credit consumer support. Once revoked, subsequent calls to POST /parent-relay-tokens for that consumer will return reportAvailable: false and no new downstream reports will be created.

Changelog​

November 2026​

  • Added POST /connect/parent-relay-tokens endpoint for credential-less report retrieval within 30 days of original report generation.