Nova API Documentation

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 plug n' play module called NovaConnect to make integrating very easy.

NovaConnect is secure, quick to integrate, and easy to use.

NovaConnect is a secure drop-in JavaScript module for your customers to easily interact with foreign bureaus through Nova’s API. Once an application through NovaConnect is successful, you can use Nova endpoints to retrieve the applicant's Nova Credit Passport™. The Nova Credit Passport™ is a comprehensive overview of applicant's international credit data. This data includes, but is not limited to, the applicant's credit history, current tradelines, payments, inquiries, and credit scores. The Nova Credit Passport™ is available in a raw JSON format or as a PDF.
For the Nova Credit Passport™ format and API status codes visit our API Documentation.

Example integration
To test the NovaConnect user flow in our sandbox environment:
  1. Click the button
  2. Select Mexico or India
  3. Complete application flow

Steps to integrate
Integrate with Nova in 3 easy steps:
  1. Obtain Nova API credentials.
  2. Add NovaConnect to your application flow on the client-side in a basic or customized way.
  3. Add small code snippets to your server-side.

The information requested from the applicant through NovaConnect will vary based on the country selected; different credit bureaus require different credentials. Nova takes care of customizing the form and handling errors with each bureau so that you don't have to.

API details
  • /connect/accesstoken
  • /connect/passport/json
  • /connect/passport/pdf
  • sandbox
  • production

Credentials and identifiers

Provided by Nova:
  • publicId: A public-facing unique identifier used in the browser
  • client_id: Your Nova API identification ID
  • secret_key: Your Nova API key (keep this secret)
Generated programatically:
  • public_token: Non-secret token used to identify a specific Nova Credit Passport™
  • access_token: A limited-lifespan token used to authorize report requests (keep this secret)

Obtain the Nova-provided credentials using our contact page or email

Client-side integration

Basic integration

Add NovaConnect to your application flow. The nova-wrapper is the div element where the Nova button will be appearing.

    <!-- Simplest Nova integration -->
    <div id="nova-wrapper"></div>
    <script simple src=""
        publicId="<Your unique Nova identifier>"
        product="<A Nova product code>"
        env="<A Nova environment variable>"

  • publicId: See credentials.
  • product: Used to identify your use case. See list of accepted codes here.
  • env: Must have either sandbox or production as value.

It is recommended that you add text around the NovaConnect button to provide context for your applicants.
Some suggestions are:

  • "If you’re new to the US, click the button below to import your foreign credit report."
  • "To improve your chances of acceptance, click the button below to import your foreign credit history."
  • "Get credit for your overseas financial history by clicking the button below."

Customized integration

NovaConnect ships with several options that allow for a richer integration.

  • country: Provide this in ISO 3166 alpha-3 format to pre-define a country.
  • callbackURL: Configure a webhook for Nova to call when information is ready. See the Server-side integration section below.
  • onSuccess: Of type function. Gets called by NovaConnect upon successful completion by the applicant. It will pass the public_token to the function.
  • onError: Of type function. Gets called by NovaConnect when an applicant is not found in the database overseas, when the applicant could not be authenticated, or when a general error occurred.
  • onExit: Of type function. Gets called by NovaConnect whenever the widget closes. This will be automatically called after onSuccess and onError.

The parameters country and product can also take a function object instead of a string to resolve to the correct value dynamically. See the product parameter in the custom integration example below.

	<!-- Nova integration with custom options -->
	<div id="nova-wrapper"></div>
	<script complex src=""></script>
	window.Nova.client = new Nova.NovaClient({
		onSuccess: function(publicToken) {},
		onError: function(error) {},
		onExit: function() {},
		publicId: "<Your unique Nova identifier>",
		country: "<A country code>",
		product: function() {
			return window.someValue; // must be a valid product code
		env: "<A Nova environment variable>",
		callbackURL: "<Your callback URL>"


Server-side integration

Step 1: Get an access_token

To get an access_token, make a request to /connect/accesstoken using your client_id and secret_key encoded using base 64.

To ensure security, please only request a new access_token once the one you currently have is expired.

	curl \
	-H "X-ENVIRONMENT: <A Nova environment variable>" \
	-H "Authorization: Basic $(echo -n '<Your client_id>:<Your secret_key>' | base64)"

	# base64 is a GNU coreutils tool


	var request = require('request');
		url: '',
		method: ‘GET’,
		headers: {
			// encode `client_id:secret_key` using base 64
			Authorization: ‘Basic <Your client_id>:<Your secret_key>’,
			X-ENVIRONMENT: '<A Nova environment variable>'
		function (err, res, body) {
			var access_token = body.access_token;
			var expiration = body.expiration;
			// persist access_token


Step 2: Set-up your webhook

Once an applicant has finished the NovaConnect flow, Nova can automatically call a callback URL to update you on the status of the Nova Credit Passport™ tied to the `public_token`. Set up the webhook and add the URL as a callbackURL parameter to your NovaConnect integration (see the client-side section). Nova will make a POST (application/json) request to the provided webhook URL to send the status code and public_token. For an overview of the codes see the status codes overview. You will need this information in the next step.

If you do not provide a callback URL you will have to call the endpoint to fetch the Nova Credit Passport™ manually.

	// Add as a callbackURL parameter
	var app = express();'/nova', function(req, res) {
		var public_token = req.body.publicToken;
		var status = req.body.status;

		if (status === 'SUCCESS') {
			// Retrieve report
		} else {
			// Handle errors


Step 3: Request a Nova Credit Passport™

To get a customer's Nova Credit Passport™, simply make a GET request to the /connect/passport endpoints using the access_token that you obtained in the previous step. Make sure to encode the access_token using base 64.

Methods to retrieve the Nova Credit Passport™:
  • /connect/passport/json: View an example JSON response here.
  • /connect/passport/pdf: View an example PDF report here.

	curl \
	-H "X-ENVIRONMENT: <A Nova environment variable>" \
	-H "X-PUBLIC-TOKEN: <A valid public_token>" \
	-H "Authorization: Bearer $(echo -n <A valid access_token> | base64)"

	# base64 is a GNU coreutils tool


	var request = require('request');
		url: '',
		method: ‘GET’,
		headers: {
			// Encode the access_token using base 64
			Authorization: ‘Bearer ‘ + '<A valid access_token>',
			X-PUBLIC-TOKEN: '<A valid public_token>',
			X-ENVIRONMENT: '<A Nova environment variable>'
		function (err, res, body) {
			var passportData = body;
			// Use the Nova Credit Passport™ JSON


Browser support


Fully supported

Versions 29 & up

Versions 5.1 & up

Versions 10 & up

Versions 42 & up

Versions 14 & up


NovaConnect is compatible with most modern mobile browsers, including most iPhone and Android devices.
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">

API Documentation

For more details on the Nova API responses and status codes refer to our API Documentation.

Integrate in under 10 minutes using our sandbox environment.
Contact us to obtain your credentials or email

Simple integration, simple pricing & dedicated support.
It couldn't be easier.