Nova API Documentation

A few steps to international credit data

Introduction

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
Host
  • https://api.neednova.com
Endpoints
  • /connect/accesstoken
  • /connect/passport/json
  • /connect/passport/pdf
Environments
  • 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!)

The API keys are accessible from the Nova dashboard. To request access to the dashboard, use our contact page or email info@neednova.com.


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="https://static.neednova.com/connect/latest/init.js"
        publicId="<Your unique Nova identifier>"
        product="<A Nova product code>"
        env="<A Nova environment variable>">
    </script>

                                
Parameters
  • simple: the type of integration.
  • 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.

Additional parameters
  • 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. Note that this solely means that everything happened as expected. This does not guarantee that an applicant's credit file was found. The function gets called with publicToken and statusCode as arguments (see below).
  • onError: Of type function. Gets called by NovaConnect when an unexpected error occurred. The function gets called with the error argument that is an error-code string (see below).
  • onExit: Of type function. Gets called by NovaConnect whenever the applicant closes the widget by the applicant's own discretion.

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.

Status codes
onSuccess status codes
  • NOT_FOUND: The applicant filled out the personal details section and we could not find your records. No report can be retrieved.
  • NOT_AUTHENTICATED: The applicant's records were found, but the authenticated phase after that failed. The applicant did not answer the questions correctly. No report can be retrieved.
  • PENDING: The applicant's records were found and the applicant was authenticated corrrectly. The application is pending and we are doing everything we can to retrieve your file. Whether the credit file is found or not is still uncertain, the webhook call from Nova will provide you with the final details (see the Server-side integration section).
onError error codes
  • REQUEST_TIMEOUT: The connections to Nova's servers were unsuccessful likely due to slow connection speeds on the client.
  • UNKNOWN_CUSTOMER: Check to make sure that the credentials used are for the right environment requested.
  • UNAUTHORIZED: Check to make sure that the credentials used are for the right environment requested.
  • INTERNAL_ERROR: The type of error is internal to Nova, you can log this for your own records.


	<!-- Nova integration with custom options -->
	<div id="nova-wrapper"></div>
	<script complex src="https://static.neednova.com/connect/latest/init.js"></script>
	<script id="nova-script">
	  var NovaConnectOptions = {
		  onSuccess: function(publicToken, status) {},
		  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>"
	  };
	  function fireNovaConnect(){clearInterval(window.NovaIntervalID),window.Nova.client=new window.Nova.NovaClient(NovaConnectOptions)}function checkIfLoaded(){return window.Nova&&window.document.getElementById("novaConnect")&&fireNovaConnect()}setTimeout(function(){clearInterval(window.NovaIntervalID)},1e4),window.NovaIntervalID=setInterval(checkIfLoaded,100);
	</script>

                                

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 https://api.neednova.com/connect/accesstoken \
	-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');
	request({
		url: 'https://api.neednova.com/connect/accesstoken',
		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). Whenever NovaConnect's onSuccess handler is called there will be a corresponding 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 https://your-domain.com/nova as a callbackURL parameter
	var app = express();
	app.post('/nova', function(req, res) {
		var public_token = req.body.publicToken;
		var status = req.body.status;

		if (status === 'SUCCESS') {
			// Retrieve report
		} else {
			// Handle errors
		}
		res.status(200).send();
	});

																	

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 https://api.neednova.com/connect/passport/json \
	-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');
	request({
		url: 'https://api.neednova.com/connect/passport/json',
		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

Desktop

Fully supported

Versions 29 & up

Versions 5.1 & up

Versions 10 & up

Versions 42 & up

Versions 14 & up

Mobile

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 info@neednova.com.

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