Nova API Documentation

A few steps to international credit data

Introduction

This quickstart guide provides information on how to integrate with and use Nova Credit's API. We've tried to make this documentation as user-friendly as possible but please drop us a line if you have any questions.

Nova Connect is secure, quick to integrate, and easy to use.
The easiest way to integrate with Nova is by using Nova Connect — a drop-in JavaScript module that allows your customers to easily interact with foreign credit bureaus through Nova's secure API. Nova Connect is an HTML form that adapts to the country selected. It takes care of user validation to increase accuracy, as well as securing data so that sensitive information never reaches your servers. The Nova API is served over HTTPS to ensure data privacy; HTTP is not supported in production.

The Nova API returns a Nova Credit Passport™ for every customer credit check
Once a request is successful, you can use specific Nova endpoints to retrieve the customer's Nova Credit Passport™ — an overview of their international credit data available in either standard JSON or PDF formats. This report contains several key data points including the customer's credit history, current tradelines, as well as a credit score and risk profile.

API Host:

api.neednova.com

Resource URL Patterns:

/connect/accesstoken
/connect/passport/json
/connect/passport/pdf

Environments:

sandbox
production

User flow

The process to retrieve international credit data is handled in 3 steps:
  1. Obtaining Nova API credentials
  2. Adding Nova Connect to your application flow
  3. Calling the /connect/passport endpoint to receive the report

The following is an example Nova Connect flow. Note that the information requested through the form may change 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.

To test the Nova Connect user flow in our sandbox environment:
  • Click the button: this loads Nova Connect in a sandbox environment
  • Select country: the sandbox environment currently supports India and Mexico
  • Complete application flow: use sandbox inputs by clicking on Get sandbox inputs

To get an example of the JSON response output, please visit our API reference.

Client-side integration

Credentials

There are several credentials that ensure the security of the request: publicId, client_id, secret_key, public_token, and access_token.

publicId
  • A public-facing unique identifier used in the browser
  • Provided by your Nova account manager
client_id
  • Your Nova username
  • Provided by your Nova account manager
secret_key
  • Your secret Nova password
  • Provided by your Nova account manager
public_token
  • ID used to identify and request a specific Nova Credit Passport™
  • Returned upon successful completion of Nova Connect
access_token
  • A secret limited-lifespan ID used to authorize report requests
  • Generated by using the publicId and calling the /connect/accesstoken endpoint

Step 1: Gain access

Obtain the credentials using our Contact Us page or email info@neednova.com.


Step 2: Add Nova to your website

Add Nova Connect to the appropriate step in your application flow.


    <!-- 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>
                                

The nova-wrapper div is where the Nova button will be appended.

The product code is used to identify your use case. For a list of the available codes, please visit the Requested Product table in our API reference. You can add a product value or a function which returns a product value.

The env value should be set to sandbox or production.

When the user successfully finishes the Nova Connect flow, Nova Connect will call an onSuccess function. This will make the public_token available to the window using the namespace window.Nova and store the value in the variable window.Nova.publicToken.


Step 3 (optional): Customize Nova with powerful options

Nova Connect ships with several options that allow for a richer integration while remaining simple to implement.

Country

Add a country parameter to the Nova script tag to predefine the country. You can also provide a string, or a function that returns a string. In both cases, please return a string compatible with the ISO 3166 alpha-3 format — for example, return 'IND' for India.


    country="<A country code>"
                                
Callback URL

Add a callbackURL parameter to the Nova script tag to enable a webhook to be called by Nova once a report is ready. See the section on server-side integration below for more information on how Nova will call this URL.


    callbackURL="<A callback URL setup on your server>"
                                
Additional custom callbacks

You can specify custom functions to be called on success, on error, or when the customer exits the Nova Connect flow. Simply instantiate the Nova object returned by the /init.js script, add it to the window.Nova.client namespace, and pass custom functions in the argument, alongside the required parameters.


    <!-- Nova integration with options -->
    <div id="nova-wrapper"></div>
    <script complex src="https://static.neednova.com/connect/latest/init.js"
        window.Nova.client = new Nova._NovaClient({
          onSuccess: function(publicToken) {},
          onErr: function(error) {},
          onExit: function() {},
          publicId: "<Your unique Nova identifier>",
          product: "<A Nova product code>",
          env: "<A Nova environment variable>",
          callbackURL: "<Your callback URL>"
        });
    </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, together encoded using base 64.

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


    # Sample request:

    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


    # Sample response:

    {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6I...",
      "exp": 1487974896
    }
                                

    // or using Node.JS
    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: Receive notifications

Once a customer has finished the Nova Connect flow, Nova can automatically call a callback URL to update you on the status of the Nova Credit Passport™ tied to this request.

Set up an endpoint on your server and add that URL as a callbackURL parameter (see the section on client-side integration for more details on how to add this parameter). Nova will make an HTTP POST request to the provided URL to send the status code and public_token. You can then use this information to call the /connect/passport endpoint and retrieve the customer's Nova Credit Passport™.

If you do not provide a callback URL, use the public_token returned on success of the Nova Connect flow as well as an access_token to retrieve a report by manualy calling the API.

This method was designed to ensure security as no sensitive data is sent to the browser directly.


    // Endpoint on your server
    // Add https://your-domain.com/your-nova-endpoint as a callbackURL parameter
    // Make sure to use HTTPS for security

    var app = express();
    app.post('/nova', function(req, res) {
        var public_token = req.body.public_token;
        var status = req.body.status;

        if (status === 'SUCCESS') {
          // Call /connect/passport endpoint using public_token & access_token
        } else {
          // Handle errors — status codes include 'ERROR' and 'NOT_FOUND'
        }
    });
                                  

Step 3: Request a Nova Credit Passport™

To get a customer's Nova Credit Passport™, simply make a GET request to the /connect/passport/json endpoint using your access_token. Please make sure to encode the access_token using base 64 or the request will fail.

Use /connect/passport/json to receive the data as a standard JSON object. View an example JSON response here.
Use /connect/passport/pdf to receive the data as a formatted pdf. View an example pdf report here.


    # Sample request:

    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


    # Sample response:

    {
      "personal": { ... },
      "meta": { ... },
      "tradelines": [ ... ],
      "inquiries": [ ... ],
      "identifiers": [ ... ],
      "addresses": [ ... ],
      "employers":[ ... ],
      "scores": [ ... ]
    }

    # For the full response object, visit our API reference.
                                

    // or using Node.JS

    var request = require('request');
    request({
        url: 'https://api.neednova.com/connect/passport/json',
        method: ‘GET’,
        headers: {
            // encode your 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;
            // do something with 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

Nova Connect 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 Reference

For more details on the Nova API JSON response, please refer to our API Reference.


Get started today

Get integration done in under 10 minutes using our sandbox environment.
Get in touch with us to obtain your credentials.

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

Contact Us