Skip to main content

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.

FieldIncome NavigatorEligibility CompassCash AtlasCredit Passport
emailRequiredRequiredRequiredRequired
firstNameRequiredRequiredRequiredRequired
lastNameRequiredRequiredRequiredRequired
dobRequiredRequiredOptional*Optional
addressOptionalOptionalOptional*—
cityOptionalOptionalOptional*Optional
stateRequiredRequiredOptional*—
zipOptionalOptionalOptional*—
phoneOptionalOptionalOptional—
consumerExternalIdOptionalOptionalOptionalOptional
languageOptionalOptionalOptional—
statedAnnualIncomeOptionalOptionalOptional—
statedEmployerNameOptional†—Optional—
statedEmployerNamesOptionalRequired‡——
  • * Cash Atlas: either a full address (address, city, state and zip) or dob must be provided.
  • † Deprecated in favor of statedEmployerNames.
  • ‡ 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

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

Required body parameters

  • dob [string] The consumer's date of birth, in the format YYYY-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) or es (Spanish). On update, pass null to 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 with statedEmployerNames parameter. Note that this field is deprecated and will be removed in a future release in favor of statedEmployerNames.
  • 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 with statedEmployerName parameter.
  • 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 consumer consumerId.
  • 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, MALFORMED_BODY, or DUPLICATE_CONSUMER_EXTERNAL_ID. DUPLICATE_CONSUMER_EXTERNAL_ID means a consumer with the provided consumerExternalId already exists; pass that consumerExternalId to the Retrieve consumer endpoint to get its consumerId.

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

  • Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key.
  • Content-Type application/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 format YYYY-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) or es (Spanish). On update, pass null to 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 with statedEmployerNames parameter. Note that this field is deprecated and will be removed in a future release in favor of statedEmployerNames.
  • 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 with statedEmployerName parameter.
  • zip [string] The US postal zip code where the consumer lives.

Possible responses

  • 200 (OK) The consumer was successfully updated.
  • 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, MALFORMED_BODY, INVALID_CONSUMER_ID, or DUPLICATE_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

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

Required path parameters

  • consumerId [string] The unique identifier for the consumer, or the consumerExternalId you assigned to it. If the value matches the consumerId of one of your consumers, that consumer is returned; otherwise it is looked up as a consumerExternalId, which must exactly match the value you provided. Percent-encode the value (for example, with encodeURIComponent); 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. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it.
  • 404 (Not Found) Consumer was not found. This could be because the consumerId or consumerExternalId was 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 language parameter (en_US or es) 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 (null when not set).

2026 October​

  • Updated the Retrieve consumer endpoint to also accept a consumerExternalId, so you can recover a consumer's consumerId after a DUPLICATE_CONSUMER_EXTERNAL_ID error.

2026 January​

  • Made statedEmployerNames optional for Eligibility Compass consumers when using the Assets Only workflow.

2025 September​