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 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 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.
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. You can find information to test sandbox users in our docs.
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
See below for a full code example of how to configure NovaConnect.
Firstly, you will need to add,init.js, a script-tag that should be loaded inside your HTML's <head>.
Secondly, you will need an unstyled div in which Nova can render. Add this div where you would like the NovaConnect button or widget to appear, and give it one of the following ids:
Lastly, you will need to add a script that configures and renders the Nova window at the bottom of your HTML body. The relative order of the div and scripts placements is important.
NovaConnect Required Parameters
You can dynamically set values for the required parameters if you pass a function to any suitable parameter but make sure to resolve with the expected variable type.
Customizing NovaConnect (optional)
You may add define or all of the following parameters to your NovaConnect configuration to further customize its content (full example shown below):
Available Prefill Keys (optional)
You may dynamically provide values for some or all of these keys, and their values will be automatically entered in NovaConnect. Applicants will still have the ability to change the values, in case their information is different in their country of origin.
Using onSuccess, onError, and onExit Hooks (optional)
You may use the onSuccess, onError, and onExit clientside hooks to know when an applicant has finished their interactions with NovaConnect. As examples, you may use these hooks to alter content on your application page or route the applicant elsewhere when the applicant completes NovaConnect (onSuccess). Alternatively, you may show a contextual message if the applicant enters a country that Nova does not support (onError).
onSuccess description & status codes
onSuccess() gets called when the applicant completes the entire NovaConnect journey and attempts to pull their international credit report. onSuccess is called with the parameters (publicToken, status). Public token is the Nova report unique identifier for this applicant. Status will be one of the following:
onError description & error types
onError() gets called when there was an internal error or an applicant was unable to complete the entire NovaConnect journey. onError is called with the parameters (publicToken, errorType). Public token is the Nova report unique identifier for this applicant. Error types will be one of the following; if no error type is provided (null or undefined), this implies an internal Nova error:
onExit() is called when the applicant voluntarily closes NovaConnect, whether or not they completed the entire NovaConnect journey. This hook does not provide any other parameters. This hook will not be fired if the applicant navigates away from your application page without closing NovaConnect.
Here's an example HTML file that utilizes the full list of configuration options:
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 1: Set-up your webhook
Once an applicant has finished the NovaConnect flow, Nova will automatically POST to your provided callback route to update you on the status of the Credit Passport® tied to the publicToken.
You must set your callback in the Nova Credit dashboard via the Developer tab.
For security, the Credit Passport® is not provided directly in the callback; instead, the callback provides a unique identifier called a public token, which you will use to retrieve a Credit Passport® in a separate call.
Here are the keys guaranteed to be returned in the webhook POST body:
The status provided in the webhook will be one of the following values:
Step 2: Get an access token
If the webhook status was SUCCESS, you should now make a request to Nova's servers to retrieve the Credit Passport®. In order to do so, you will need to first fetch an access token using your Nova client id and secret key. Access tokens are time-scoped to prevent malicious usage should someone obtain one. You should retrieve a new access token each time you intend to retrieve a Credit Passport®. To get an accessToken, make a request to /connect/accesstoken using the credentials found on your Nova dashboard.
The access token endpoint is accessible by sending a GET request to: https://api.neednova.com/connect/accesstoken
Example request for access token
If your request to retrieve an access token was successful, Nova will respond with a status code of 200. The response body will be a JSON containing the following keys:
Example successful response body with access token:
Step 3: Request a Credit Passport®
Once you have fetched an access token, simply make a GET request to the /connect/v2/passport endpoints using the accessToken that you obtained in the previous step and the publicToken (unique identifier for the report) provided by the webhook. Make sure to encode the accessToken using base 64.
You can retrieve the Credit Passport® as a JSON or PDF stream (more details in our API docs). Here are examples of both:
The JSON endpoint is accessible by sending a GET request to: https://api.neednova.com/connect/v2/passport/json.
The PDF endpoint is accessible by sending a GET request to: https://api.neednova.com/connect/v2/passport/pdf.
The JSON endpoint will return the Credit Passport® directly in the response body. Depending on your web application framework, you may need to convert the response body into a JSON object, such as JSON.parse(res.body).
The PDF endpoint will return the Credit Passport® directly in the response body with content type: application/pdf; you don't need to do any explicit encoding/decoding on your own, as your web application framework should know how to interpret the data given the content type. Both streaming and using a (multi-part) blocking GET request that receives the full content should work and in both in cases, you're able to simply write the response body to disk and it will render a pdf if saved with the pdf suffix.
Example request for Credit Passport®
View our API docs for details and examples of the contents of the Credit Passport®.
Here is a full example of how to define a route for the callback url and retrieve the corresponding Credit Passport®:
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 Credit 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">