Parent Configuration via API

If your account has been configured as a “Parent”, that allows you to leverage a hierarchy framework wherein then you can create multiple customer accounts and products, as represented in the diagram below.

Account Hierarchy Diagram

Each child account has its own publicId
Each child account can have one or more products. Each Product has its own productId.

This can be configured for you by your Nova Representative, or can be done via the Nova Credit Dashboard. However, if you have a large account, there is also an option to do this via API as described below.

For more general information about the Nova Credit APIs, view your corresponding quickstart guide (Credit Passport Quickstart, Income Navigator Quickstart, Cash Atlas Quickstart).

Child Account `publicId` creation

Create a new account using following endpoint:

POST https://api.novacredit.com/accounts

Required headers‍

Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.
Content-Type Should be set to application/json.

Required body parameters

accountName [string]: Name of account to be created. Must be unique.

Optional body parameters

displayName [string]: Display name of account to be created. Optional and can be re-used across multiple accounts.

Possible responses

201 (Success) The newly created publicId is returned if the account does not exist
400 (Bad Request) An account with the provided accountName exists

Example request

curl --location --request POST 'https://api.novacredit.com/accounts' \
--header 'Authorization: Basic {Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accountName": "{accountName}",
    "displayName": "{displayName}"
}'

Example response

{
	"publicId": "7292265cd901306dd78e13e8c09ec269c872ad863aff6c15af9799d9de6c02ds"
}

Example error response

{
	"error": "DUPLICATE_CUSTOMER"
}

Get or Create Child Account

To get or create a child account, you may use the PUT endpoint which follows a similar format as the POST endpoint.

PUT https://api.novacredit.com/accounts

If an account bearing the provided accountName already exists, the PUT endpoint will return 200 (OK) and the publicId of the existing account.

Product `productId` Creation

Create a new product for a child account using the following endpoint:

POST https://api.novacredit.com/accounts/{publicId}/products

Required body parameters

productName [string]: The external name of the product applicant is applying for.

Optional body parameters

displayName [string]: Display name of product to be created. Optional and can be re-used across multiple products.

Required headers‍

Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.
Content-Type Should be set to application/json.

Possible responses

201 (Success) The newly created productId is returned
400 (Bad Request) A product with the provided productName already exists

Example request

curl --location --request POST 'https://api.novacredit.com/accounts/{publicId}/products' \
--header 'Authorization: Basic {Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "productName": "{productName}",
    "displayName": "{displayName}"
}'

Example response

{
	"productId": "e80f68b0-6108-11ed-856b-35a9ae57feb2"
}

Example error response

{
	"error": "DUPLICATE_PRODUCT"
}

Get or Create Product

To get or create a product, you may use the PUT endpoint which follows a similar format as the POST endpoint.

PUT https://api.novacredit.com/accounts/{publicId}/products

If a product bearing the provided productName already exists, the PUT endpoint will return 200 (OK) and the productId of the existing product.

Configuration Management

A workflow is a user flow designed for an applicant to provide data to your account for your verification. Workflows are a subset of the configurations assigned to any account or product. When child accounts and products are created, they do not have a product configuration assigned. They inherit the product configurations by default; this will be marked by the inherited property.

Config API Diagram

They can be assigned a different workflow via an API, using the account publicId and product productId. This API allows you to get the list of available configurations, assign an available configuration and review the configuration assigned to a customer account or product. If you would like to use it, reach out to your Nova Representative to enable this feature.

List of available configurations

Get the list of available configurations using the following endpoint:

GET https://api.novacredit.com/config/v1/product-configurations

Required headers‍

Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.

Possible responses‍‍

200 (OK) An array of objects representing possible configurations will be returned. The configuration objects will have the following keys:
- id: The unique identifier for the product configuration.
- novaProduct: The Nova Credit product for which the configuration is available. For now this will always be “Income Navigator”.
- alias: The name of the configuration defined by your Nova Representative.
403 (Forbidden) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS.

Example request

curl --location --request GET 'https://api.novacredit.com/config/v1/product-configurations' \
--header 'Authorization: Basic {Token}'

Example response

[
	{
		"id": "cffbb4f4-c6cd-4e97-9a62-300ccd865caf",
		"novaProduct": "Income Navigator",
		"alias": "Bank Then Paystub"
	},
	{
		"id": "0766890d-0621-40bd-b3b3-a3f7e850d6a3",
		"novaProduct": "Income Navigator",
		"alias": "Payroll or Bank"
	}
]

Product Configuration Assignment

Assign an available configuration to a child account or product using the following endpoint:

PUT https://api.novacredit.com/config/v1/product-configuration-assignments/:productConfigId

Rules of Assignment

Parent accounts cannot be assigned a workflow via the API. Reach out to your Nova Representative for assistance with updates to your parent account.
New workflows cannot be created via the API. Your Nova Representative will need to create the workflow, to make it available for assignment via the API.
Child accounts and products inherit product configurations from the parent account by default.
If a product has a unique product configuration assigned to it, updating the child account it is attached to will not overwrite the configuration assignment for the product.
If a product does not have a unique configuration assigned to it, then its configuration will get updated every time the child account gets updated.

Required headers‍

Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.

Required URL parameters

productConfigId [string] The ID of the Nova product configuration that you want to assign to your child account or product.

Required body parameters

type [string] The type of assignment you want to create. This should be either account or product.
id [string] The id of the account or product that you want to assign this configuration to.

Possible responses‍‍

200 (OK) An object representing the updated configuration will be returned. The result object will have the following keys:
- type: The type of configuration set (account or product)
- id: The id of the account or product
- productConfigId: The id of the configuration that was assigned to this account or product
400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS, MALFORMED_BODY.
403 (Forbidden) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
404 (Not Found) Not Found. You used a product config ID or account/product ID that does not exist. Error will be one of UNKNOWN_CHILD_ACCOUNT or UNKNOWN_PRODUCT_CONFIGURATION.

Example request

# Assign a product configuration to a child account
curl --location --globoff --request PUT 'https://api.novacredit.com/config/v1/product-configuration-assignments/d272a86e-439b-4179-9394-da2dd164fa40' \
--header 'Authorization: Basic {Token}'
--data '{
    "type": "account",
    "id": "0a78c605-e97c-461a-a400-63d53d882a47"
}'

Example response

{
	"type": "account",
	"id": "0a78c605-e97c-461a-a400-63d53d882a47",
	"productConfigId": "d272a86e-439b-4179-9394-da2dd164fa40"
}

Example request

# Assign a product configuration to a child product
curl --location --globoff --request PUT 'https://api.novacredit.com/config/v1/product-configuration-assignments/d272a86e-439b-4179-9394-da2dd164fa40' \
--header 'Authorization: Basic {Token}'
--data '{
    "type": "product",
    "id": "49b3f46c-eb70-4cc5-936f-ca73de3e00f7"
}'

Example response

{
	"type": "product",
	"id": "49b3f46c-eb70-4cc5-936f-ca73de3e00f7",
	"productConfigId": "d272a86e-439b-4179-9394-da2dd164fa40"
}

Review Assigned Configuration

Review the assigned configuration for the products belonging to a child account using the publicId. This would provide a list of all active products linked to the child account, with their assigned product configuration. Products inheriting their product configuration will display an inherited value of true.

GET https://api.novacredit.com/config/v1/accounts/{publicId}/products

Required headers‍

Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.

Possible responses

200 (OK) An array of objects representing assigned configurations will be returned. The configuration objects will have the following keys:
- productId: The ID for the product of the child account
- name: The name of the child account's product
- createdAt: The timestamp of product creation
- updatedAt: The timestamp of the latest product update
- productConfiguration: The Nova product configuration settings for this child account's product
  - id: The ID of the product configuration. If the product configuration is inherited, this ID will represent the inherited workflow.
  - alias: The alias of the product configuration. If the product configuration is inherited, this alias will represent the inherited workflow.
  - inherited: Whether the product configuration is being inherited from a child account or parent account.
403 (Forbidden) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
404 (Not Found) Not Found. You used a child account publicId that does not exist. Error message will be UNKNOWN_CHILD_ACCOUNT.

Example request

curl --location --globoff 'https://api.novacredit.com/config/v1/accounts/3a5699d2980d7cefd3f983c0e00549c90495a8786788c7d6abf72a9e25a4cfc4/products' \
--header 'Authorization: Basic {Token}'

Example response

[
	{
		"productId": "d272a86e-439b-4179-9394-da2dd164fa40",
		"name": "Child Account API Child Product 1",
		"createdAt": "2024-12-16T19:50:24.066Z",
		"updatedAt": "2024-12-16T19:50:24.066Z",
		"productConfiguration": {
			"id": "832fb756-dd58-4828-8c81-39ec00c9f3dd",
			"alias": "Bank or Payroll",
			"inherited": false
		}
	},
	{
		"productId": "a7949099-b264-48a3-b5e9-9e0b2cddacff",
		"name": "Child Account API Child Product 2",
		"createdAt": "2024-12-16T19:50:24.066Z",
		"updatedAt": "2024-12-16T19:50:24.066Z",
		"productConfiguration": {
			"id": "19d973a7-fb86-887e-84f6-7902aaedbd50",
			"alias": "Bank or Paystub",
			"inherited": true
		}
	}
]

Delete Product Configuration Assignment

Delete a product configuration assignment for a child account or product, allowing it to inherit configuration from its parent using the following endpoint:

DELETE https://api.novacredit.com/config/v1/product-configuration-assignments

Required headers‍

Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.

Required body parameters

type [string] The type of assignment you want to delete. This should be either account or product.
id [string] The id of the account or product that you want to remove the configuration assignment from.

Possible responses‍‍

204 (No Content) The configuration assignment was successfully deleted. The entity will now inherit its configuration from its parent. Note that this endpoint will also return a 204 for child accounts and products that are already inheriting from their parent.
400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS, or MALFORMED_BODY.
403 (Forbidden) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
404 (Not Found) You used a child account publicId that does not exist. Error message will be UNKNOWN_CHILD_ACCOUNT.

Example request

# Delete a product configuration assignment from a child account
curl --location --request DELETE 'https://api.novacredit.com/config/v1/product-configuration-assignments' \
--header 'Authorization: Basic {Token}' \
--data '{
    "type": "account",
    "id": "0a78c605-e97c-461a-a400-63d53d882a47"
}'

Changelog

2025 July

Updated GET https://api.novacredit.com/config/v1/accounts/{publicId}/products to include new inherited property and no longer return null for id or alias

Change Log

July 2025

added POST endpoints for creating child accounts and products
added optional displayName parameter to POST endpoints for creating child accounts and products

Child Account publicId creation​

Product productId Creation​

Configuration Management​

List of available configurations​

Product Configuration Assignment​

Review Assigned Configuration​

Delete Product Configuration Assignment​

Changelog​

2025 July​

Change Log​

July 2025​

Child Account `publicId` creation

Product `productId` Creation

Configuration Management

List of available configurations

Product Configuration Assignment

Review Assigned Configuration

Delete Product Configuration Assignment

Changelog

2025 July

Change Log

July 2025