Consumers API Reference
Instead of sending an applicant's PII data directly on the NovaConnect widget register() function, the initialization endpoint or the invite endpoints, you can first create a Consumer object and then pass its consumerId to any of these integration options. The advantage is that if you need a user to go through NovaConnect multiple times, you are able to easily group these visits together. See your product's quickstart for details on each integration option: Income Navigator, Eligibility Compass, Cash Atlas or Credit Passport.
Fields by Nova Product
Each Nova Product requires a different set of consumer fields. Required fields must be provided when creating a consumer; all fields are optional when updating a consumer.
If you are using or intend to use our Multi-Product Token functionality, you must provide the superset of required fields across the products, e.g. to use Multi-Product Token with Cash Atlas and Income Navigator reports, you must provide firstName, lastName, dob, email and state.
| Field | Income Navigator | Eligibility Compass | Cash Atlas | Credit Passport |
|---|---|---|---|---|
email | Required | Required | Required | Required |
firstName | Required | Required | Required | Required |
lastName | Required | Required | Required | Required |
dob | Required | Required | Optional* | Optional |
address | Optional | Optional | Optional* | — |
city | Optional | Optional | Optional* | Optional |
state | Required | Required | Optional* | — |
zip | Optional | Optional | Optional* | — |
phone | Optional | Optional | Optional | — |
consumerExternalId | Optional | Optional | Optional | Optional |
language | Optional | Optional | Optional | — |
statedAnnualIncome | Optional | Optional | Optional | — |
statedEmployerName | Optional† | — | Optional | — |
statedEmployerNames | Optional | Required‡ | — | — |
*Cash Atlas: either a full address (address,city,stateandzip) ordobmust be provided.†Deprecated in favor ofstatedEmployerNames.‡Optional when using the Assets Only workflow.
Select your Nova Product to see its fields and examples in the sections below.
Create consumer endpoint
This endpoint may be used to create consumers.
POST https://api.novacredit.com/connect/consumers
Required headers
AuthorizationBasic Auth, containing the base-64 encoded string of yourclient_id:secret_key.Content-Typeapplication/json.
Required body parameters
dob [string]The consumer's date of birth, in the formatYYYY-MM-DD. Must be between 1 and 110 years old.email [string]The email address of the consumer. Max length 100 characters.firstName [string]The first name of the consumer. Less than 255 characters and contain only alphabetical, unicode, dots, apostrophes and dashes.lastName [string]The last name of the consumer. Less than 255 characters and contain only alphabetical, unicode, dots, apostrophes and dashes.state [string]The two letter US state or territory code where the consumer lives.
Optional body parameters
address [string]The street address of the consumer. Max length 100 characters.city [string]The city where the consumer lives. Max length 100 characters.consumerExternalId [string]Pass in a unique internal identifier for your own records. Note that this MUST be unique across all other Consumers associated with your account and MUST NOT include any consumer PII. Max length 64 characters.language [string | null]The consumer's preferred language, as a case-sensitive ISO language code:en_US(English) ores(Spanish). On update, passnullto clear it.phone [string]The phone number of the consumer. Max length 255 characters.statedAnnualIncome [integer]The annual income in dollars as stated by the consumer. Must be an integer between 0 and 2147483647.statedEmployerName [string]Deprecated The name of the consumer's current employer. Mutually exclusive withstatedEmployerNamesparameter. Note that this field is deprecated and will be removed in a future release in favor ofstatedEmployerNames.statedEmployerNames [array of strings]The names of the consumer's current employers, with a minimum of 1 name and a maximum of 6 names. Mutually exclusive withstatedEmployerNameparameter.zip [string]The US postal zip code where the consumer lives.
Example request
curl -X POST \
https://api.novacredit.com/connect/consumers \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY=' \
-d '{
"address": "456 7th Street",
"city": "Modesto",
"consumerExternalId": "2e63a13f-4e08-4c33-9450-2fe9f7d258f4",
"dob": "1995-10-01",
"email": "raymond@email.com",
"firstName": "Raymond",
"language": "es",
"lastName": "Marshal",
"phone": "+12134567890",
"state": "CA",
"statedAnnualIncome": 18000,
"statedEmployerNames": [
"Raymond'\''s Designs"
],
"zip": "95313"
}'
Possible responses
200 (OK)The consumer was successfully created. Returns the identifier of the created consumerconsumerId.403 (Forbidden)Unauthorized request. Yourclient_idorsecret_keywas incorrect, or you did not correctly base-64 encode it.400 (Bad Request)Malformed request, headers or missing required parameters. Error will be one ofMALFORMED_HEADERS,MALFORMED_BODY, orDUPLICATE_CONSUMER_EXTERNAL_ID.DUPLICATE_CONSUMER_EXTERNAL_IDmeans a consumer with the providedconsumerExternalIdalready exists; pass thatconsumerExternalIdto the Retrieve consumer endpoint to get itsconsumerId.
Example response
{
"consumerId": "987fcdeb-51a2-43d7-8f9e-123456789abc"
}
Update consumer endpoint
This endpoint may be used to update consumers.
PATCH https://api.novacredit.com/connect/consumers/:consumerId
Required headers
AuthorizationBasic Auth, containing the base-64 encoded string of yourclient_id:secret_key.Content-Typeapplication/json.
Required path parameters
consumerId [string]The unique identifier for the consumer to update.
Optional body parameters
All fields are optional for updates. You can update any combination of the following fields:
address [string]The street address of the consumer. Max length 100 characters.city [string]The city where the consumer lives. Max length 100 characters.consumerExternalId [string]Pass in a unique internal identifier for your own records. Note that this MUST be unique across all other Consumers associated with your account and MUST NOT include any consumer PII. Max length 64 characters.dob [string]The consumer's date of birth, in the formatYYYY-MM-DD. Must be between 1 and 110 years old.email [string]The email address of the consumer. Max length 100 characters.firstName [string]The first name of the consumer. Less than 255 characters and contain only alphabetical, unicode, dots, apostrophes and dashes.language [string | null]The consumer's preferred language, as a case-sensitive ISO language code:en_US(English) ores(Spanish). On update, passnullto clear it.lastName [string]The last name of the consumer. Less than 255 characters and contain only alphabetical, unicode, dots, apostrophes and dashes.phone [string]The phone number of the consumer. Max length 255 characters.state [string]The two letter US state or territory code where the consumer lives.statedAnnualIncome [integer]The annual income in dollars as stated by the consumer. Must be an integer between 0 and 2147483647.statedEmployerName [string]Deprecated The name of the consumer's current employer. Mutually exclusive withstatedEmployerNamesparameter. Note that this field is deprecated and will be removed in a future release in favor ofstatedEmployerNames.statedEmployerNames [array of strings]The names of the consumer's current employers, with a minimum of 1 name and a maximum of 6 names. Mutually exclusive withstatedEmployerNameparameter.zip [string]The US postal zip code where the consumer lives.
Possible responses
200 (OK)The consumer was successfully updated.403 (Forbidden)Unauthorized request. Yourclient_idorsecret_keywas incorrect, or you did not correctly base-64 encode it.400 (Bad Request)Malformed request, headers or missing required parameters. Error will be one ofMALFORMED_HEADERS,MALFORMED_BODY,INVALID_CONSUMER_ID, orDUPLICATE_CONSUMER_EXTERNAL_ID.
Example request
curl -X PATCH \
https://api.novacredit.com/connect/consumers/987fcdeb-51a2-43d7-8f9e-123456789abc \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY=' \
-d '{
"firstName": "Arthur",
"lastName": "Cohen"
}'
Example response
{}
Retrieve consumer endpoint
This endpoint may be used to retrieve the PII and visits of consumers, by consumerId or by the consumerExternalId you assigned to the consumer.
Looking up a consumer by consumerExternalId is intended to recover its consumerId when the Create consumer endpoint returns DUPLICATE_CONSUMER_EXTERNAL_ID, or when you did not store the consumerId returned on creation. For all other lookups, store and use the consumerId.
GET https://api.novacredit.com/connect/consumers/:consumerId
Required headers
AuthorizationBasic Auth, containing the base-64 encoded string of yourclient_id:secret_key.
Required path parameters
consumerId [string]The unique identifier for the consumer, or theconsumerExternalIdyou assigned to it. If the value matches theconsumerIdof one of your consumers, that consumer is returned; otherwise it is looked up as aconsumerExternalId, which must exactly match the value you provided. Percent-encode the value (for example, withencodeURIComponent); a+is treated as a literal plus sign, not a space.
Possible responses
200 (OK)Consumer is returned with all available fields.400 (Bad Request)Malformed request or headers, for example a value longer than 64 characters.403 (Forbidden)Unauthorized request. Yourclient_idorsecret_keywas incorrect, or you did not correctly base-64 encode it.404 (Not Found)Consumer was not found. This could be because theconsumerIdorconsumerExternalIdwas not correct.
Example request
curl -X GET \
https://api.novacredit.com/connect/consumers/987fcdeb-51a2-43d7-8f9e-123456789abc \
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY='
Example request by consumerExternalId
curl -X GET \
https://api.novacredit.com/connect/consumers/your-internal-id-123 \
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY='
Example response
{
"address": "456 7th Street",
"city": "Modesto",
"consumerExternalId": "2e63a13f-4e08-4c33-9450-2fe9f7d258f4",
"consumerId": "987fcdeb-51a2-43d7-8f9e-123456789abc",
"dob": "1995-10-01",
"email": "raymond@email.com",
"firstName": "Raymond",
"language": "es",
"lastName": "Marshal",
"phone": "+12134567890",
"state": "CA",
"statedAnnualIncome": 18000,
"statedEmployerNames": [
"Raymond's Designs"
],
"visits": [
{
"publicToken": "36128cc3-bde6-4026-8abd-4cbb790d82d2"
}
],
"zip": "95313"
}
Using consumerId
How to pass consumerId to NovaConnect, code example
<html>
<head>
<!-- Other head files here -->
<script src="https://static.novacredit.com/connect/v2/init.js"></script>
</head>
<body>
<div id="nova-embed"></div>
<script>
window.Nova.register({
env: 'sandbox',
publicId: 'your_sandbox_public_id',
productId: 'your_sandbox_product_id',
consumerId: '987fcdeb-51a2-43d7-8f9e-123456789abc'
});
</script>
</body>
</html>
How to pass consumerId to NovaConnect Initialization Endpoint, example request
curl -X POST \
https://api.novacredit.com/connect/initialization \
-H 'Content-Type: application/json' \
-H 'X-PRODUCT-ID: 3c2da600-17ee-11e8-8a0e-5158039db37e' \
-H 'X-PUBLIC-ID: aa2eebe1-c02a-11e6-88fa-fbe350f5820f' \
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY=' \
-d '{
"token": "JWT",
"consumerId": "987fcdeb-51a2-43d7-8f9e-123456789abc"
}'
How to pass consumerId to NovaConnect Invite Endpoint, example request
curl -X POST \
https://api.novacredit.com/connect/invite \
-H 'Content-Type: application/json' \
-H 'X-PUBLIC-ID: aa2eebe1-c02a-11e6-88fa-fbe350f5820f' \
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY=' \
-d '{
"emailTemplate": "INVITE_VOI",
"productId": "3c2da600-17ee-11e8-8a0e-5158039db37e",
"consumerId": "987fcdeb-51a2-43d7-8f9e-123456789abc"
}'
How to pass consumerId to NovaConnect Invite Link Endpoint, example request
curl -X POST \
https://api.novacredit.com/connect/invite-link \
-H 'Content-Type: application/json' \
-H 'X-PUBLIC-ID: aa2eebe1-c02a-11e6-88fa-fbe350f5820f' \
-H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY=' \
-d '{
"emailTemplate": "INVITE_VOI",
"productId": "3c2da600-17ee-11e8-8a0e-5158039db37e",
"consumerId": "987fcdeb-51a2-43d7-8f9e-123456789abc"
}'
Changelog
2026 November
- Moved the Consumer endpoints documentation from each product quickstart to this page, with a table of the fields required for each Nova Product.
- Added optional
languageparameter (en_USores) to the Create consumer and Update consumer endpoints for Income Navigator, Eligibility Compass and Cash Atlas. - Updated the Retrieve consumer endpoint to always return the consumer's
language(nullwhen not set).
2026 October
- Updated the Retrieve consumer endpoint to also accept a
consumerExternalId, so you can recover a consumer'sconsumerIdafter aDUPLICATE_CONSUMER_EXTERNAL_IDerror.
2026 January
- Made
statedEmployerNamesoptional for Eligibility Compass consumers when using the Assets Only workflow.
2025 September
- Added the Consumer endpoints to create, update and retrieve consumers.