A few steps to international credit data
This quickstart guide provides information on how to integrate with Nova and use the API to retrieve a Nova Credit Passport®. Nova provides a secure, plug and play module called NovaConnect to make integrating quick and easy.
NovaConnect is secure, quick to integrate, and easy to use.
Your applicants can use NovaConnect to authenticate with a foreign credit bureau and authorize Nova to fetch their report. Nova takes care of customizing the form and handling errors with each bureau so that you don't have to. The Nova Credit Passport® data includes, but is not limited to, the applicant's credit history, current tradelines, payments, inquiries, and credit scores.
Once a user has successfully gone through the NovaConnect flow, you can use the Nova dashboard to retrieve the applicant's Nova Credit Passport®. You can also use the optional server-side integration to retrieve reports automatically.
Try NovaConnect now by clicking on the Nova button (web & mobile compatible):
Your account keys
Your account keys are found on the Developer tab of your dashboard.
Programmatically generated tokens
Nova provides two environments: one suitable for developing and testing your integration and one for production requests. The former provides a safe place for you to access Nova's resources and test different response types from the foreign credit bureaus using dummy data.
Both environments have their own publicId, clientId, secretKey, publicTokens, and accessTokens. Please be sure to use the correct credentials for the resource's environment you are requesting. Using the wrong credentials or tokens for the specified environment usually leads to errors such as UNKNOWN_CUSTOMER.
Step 1: Product configuration
Applicants use NovaConnect as part of an application process for one of your product offerings, be it a property lease at a specific building, a credit card or an auto insurance product. To help you identify which product an applicant has applied for, you first have to create a productId using your dashboard account.
To create a product, login to your Nova dashboard account, click on the Products tab and click 'Add a Product'. Once you have created your products, you can view their productIds by clicking the Developer tab and Product IDs
Step 2: Add NovaConnect to your page
It is recommended that you place the init.js loading script-tag inside your HTML's <head>. Place the nova-button div where you would like the NovaConnect button to appear, and place the script that registers the Nova window at the bottom of your HTML body. The relative order of the div and scripts placements is important. Here's an example HTML file:
NovaConnect Register Parameters
You can dynamically set values if you pass a function to any suitable parameter but make sure to resolve with the right type.
Step 3: Add a call to action
We recommend that you add text around the NovaConnect button to provide context for your applicants. Suggestions include:
"New to the U.S.? Click on the button below to import your foreign credit report."
"To improve your chances of acceptance, click on the button below to import your foreign credit history."
"Click on the button below to request your foreign credit history."
Step 4: Customize NovaConnect (optional)
onSuccess status codes
onError error types
Step 1: Set-up your webhook
Once an applicant has finished the NovaConnect flow, Nova can automatically call your provided callback to update you on the status of the Nova Credit Passport® tied to the publicToken.
You can set your callback in the Nova Credit dashboard via the Developer tab. For an overview of the codes see our API docs. You will need this information in the next step.
Here's an example of how to define a route for the callback url using NodeJS and Express:
Step 2: Get an access token
To get an accessToken, make a request to /connect/accesstoken using your credentials. You will use this accessToken to access your customer's Nova Credit Passports®.
The access token endpoint is accessible by sending a GET request to: https://api.neednova.com/connect/accesstoken
Only request a new accessToken once the one you currently have is expired. The response includes the accessToken's expiration date as a unix timestamp.
Step 3: Request a Nova Credit Passport®
Once you have received a webhook that the Passport is ready, simply make a GET request to the /connect/v2/passport endpoints using the accessToken that you obtained in the previous step. Make sure to encode the accessToken using base 64.
Nova Credit Passport® format examples
The passport endpoint is accessible by sending a GET request to: https://api.neednova.com/connect/v2/passport/json
cURL example request
View our API reference for sample responses.
The invite endpoint may be used to send an email inviting your applicant to fill out NovaConnect. The invitation is sent to the specified applicant’s email address and includes a link to a pre-configured NovaConnect widget hosted on Nova’s domain. Once the applicant completes NovaConnect, their Credit Passport status and report is accessible like any other Passport, both via the Nova Credit dashboard and programmatically via API.
To use the invite endpoint, you must set the appropriate headers and send a valid JSON body. The NovaConnect and server-side API keys are accessible from your Nova Credit dashboard.
The invite endpoint is accessible by sending a POST request to: https://api.neednova.com/connect/invite
Required body parameters
Using ID Aliases
To save you having to manage Nova IDs in the form of product_id and public_id, where you are a reseller who manages multiple customers, you can substitute both IDs for your own providing they've been communicated to your Nova Account Manager. Both parameters can be passed in the body. Please consult your Nova Account Manager upon setting up.
Optional body parameters
There are several optional parameters you may include in the request body. Some allow the NovaConnect widget to be prefilled based on information you already have about your applicant, so they don’t need to enter it again. Others can be used to determine invite endpoint configurations.
Optional body parameters you may include
To enable prefilling for NovaConnect widgets sent via the invite endpoint, include the enabledPrefills key in your request body. enabledPrefills should be an array that is a list of what you would like to prefill.
The prefill options are:
You may include one, multiple, or all of the available keys to prefill. Note that any keys you specify in enabledPrefills that you do not send data for will not be prefilled.
Choosing an email template
To determine an email template to be sent to the applicant, include the emailTemplate key in your request body. The value should be a string that matches one of the strings below, each representing a different email template that can be sent out.
Acceptable emailTemplate values:
The string is case-insensitive, but must match one of the values above. The default email template INVITE is sent out should you choose not to use the emailTemplate key.
cURL example request
There are several optional parameters you may include in the request body. These allow the NovaConnect widget to be prefilled based on information you already have about your applicant, so they don’t need to enter it again.
Your NovaConnect widget can be configured to bill the applicant a specified fee if a foreign credit report is successfully found. This allows you to offer NovaConnect to your customers while also passing on fees incurred to your applicant. Contact your Nova Credit representative to learn more.
Include the following script in your HTML's <head> tag to ensure that content scales correctly on smaller screens <meta name="viewport" content="width=device-width, initial-scale=1.0">