Quickstart Guide

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

Example integration

Try NovaConnect now by choosing an integration type (web & mobile compatible):

EmbeddedButton

Credentials & Identifiers

The NovaConnect and server-side API keys are accessible from your Nova dashboard. To request access, use our contact form or login if you already have an account set up.

Your account keys

Your account keys are found on the Developer tab of your dashboard.

  • publicId: Used when integrating NovaConnect to identify your account
  • clientId: Your Nova API identifier for server-side integrations. You will use this to programmatically access resources
  • secretKey: Your Nova API key for server-side integrations (keep this secret). You will use this to programmatically access resources

Programmatically generated tokens

  • publicToken: Identifies a specific Credit Passport®
  • accessToken: Used to authorize Credit Passport® requests for server-side integrations (keep this secret). You will use this token to programmatically fetch Credit Passports®

Sandbox & Production Environments

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.

Available environments

  • sandbox: Suitable for development and testing. You may fetch sandbox reports with this environment
  • production: Use for production-level interactions with applicants and foreign credit bureaus

Client-Side Integration

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:

  • nova-embed Use this div id to render the NovaConnect widget inline, as an embedded widget (see example above). Nova will appear alongside other elements of your application.
  • nova-button Use this div id to render the NovaConnect "import credit report" button (see example above). Nova will fill the entire screen.

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

  • publicId [string]: See credentials
  • env [string]: Either 'sandbox' or 'production'. See environments
  • productId [function | string]: See Step 1

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):

  • userArgs [function | string] Pass in the unique applicant identifier from your system. This will be returned to you in our webhook call and in the API JSON response. You will use this identifier to match the Nova public token (Nova report identifier) with the applicant in your system.
  • onSuccess [function] Called with arguments (publicToken, status) when an applicant successfully completes the NovaConnect flow. See Using onSuccess, onError, and onExit Hooks below.
  • onError [function] Called with arguments (publicToken, error) when an unexpected error occurs.  See Using onSuccess, onError, and onExit Hooks below.
  • onExit [function] Called without arguments when the applicant closes NovaConnect voluntarily.  See Using onSuccess, onError, and onExit Hooks below.
  • country [function | string] Provide an ISO country code to load NovaConnect with a pre-specified country.
  • language [function | string] Specify the language NovaConnect should open with as a 639-1 language code. (Applicants also have the ability of changing the language themselves within NovaConnect). Note that not all languages are available for all countries. Contact your Nova representative to learn more.
  • prefill [function | object] Prefill specific NovaConnect form fields for the applicant by passing an object which maps keys to string values. See Available Prefill Keys below.
  • hideButton [boolean] Use a custom button instead of the default Nova button. To display NovaConnect call when hideButton is set to true, call window.Nova.fire() programmatically in your clientside Javascript.

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.

  • firstName The first name of the applicant
  • lastName The last name of the applicant
  • dob The date of birth of the applicant in ISO date format
  • email The email address of the applicant
  • city The most recent city where the applicant has lived in the foreign country

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:

  • NOT_FOUND: Unable to retrieve records of the applicant
  • NOT_AUTHENTICATED: Unable to authenticate the applicant
  • PENDING: The credit report request is received and a result will be available in your dashboard or by webhook call

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:

  • UNSUPPORTED_COUNTRY: The applicant entered a country that Nova does not support. They are unable to complete the Nova flow as a result.

onExit description

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:

<html>
<head>
    <!-- Other head files here -->
    <script src="https://static.neednova.com/connect/v2/init.js"></script>
</head>
<body>
    <!-- Button or embedded widget placement div -->
    <div id="nova-embed"></div>

    <script>
        window.Nova.register({
         env: 'sandbox',
         publicId: '18efe5b7608fed4c91ff9c', // Sandbox value representing your company
         productId: 'e0c59fc0-86c4-11e8-8d8b', // Sandbox value representing your product
         language: 'fr', // Language code
         country: 'IND', // Country code
         userArgs: 'your_applicant_id', // Applicant identifier from your systems
         onSuccess: function (publicToken, status) {
          // Applicant has completed NovaConnect and a webhook will be called
          console.log(publicToken);
          console.log(status);
         },
         onExit: function () {
          // Applicant exited the NovaConnect widget
          console.log('Applicant exited NovaConnect');
         },
         onError: function (publicToken, error) {
          // Applicant was unable to complete NovaConnect
          console.log(publicToken);
          if (error === 'UNSUPPORTED_COUNTRY') {
           console.log('Applicant entered an unsupported country');
          } else {
           console.log('Applicant encountered an internal error');
          }
         },
         prefill: {
          firstName: 'Raj',
          lastName: 'Du',
          dob: '1993-01-25',
          email: 'rajdu@email.com',
          city: 'New Delhi',
         },
       });
    </script>
</body>
</html>
                                


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."

Server-Side Integration

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:

{
  publicToken: '812dfac3-ce5a-4da3-843b', // Unique identifier to retrieve Credit Passport
  status: 'SUCCESS', // Result of report
  userArgs: 'your_applicant_id' // Specified in your clientside configuration
}


The
status provided in the webhook will be one of the following values:

  • SUCCESS: The credit report request was successful and you may now retrieve the Credit Passport® for the given applicant
  • NOT_FOUND: The applicant was not found in the international bureau's system. You should make your credit decision without a Credit Passport®
  • NOT_AUTHENTICATED: The applicant was found but they did not pass the required authentication questions to verify their identity. You should make your credit decision without a Credit Passport®
  • ERROR: An internal error occurred and the Nova Credit Passport™ could not be compiled. Please send a message to support@neednova.com with the publicToken.


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

Required headers

  • X-ENVIRONMENT: sandbox or production
  • Authorization: Basic Auth, containing the strict base-64 encoded string of your client_id:secret_key (ensure you use the corresponding client id and secret key to the environment you define)

Example request for access token


require('request').request({
  url: 'https://api.neednova.com/connect/accesstoken',
  method: 'GET',
  headers: {
    Authorization: 'Basic ' + new Buffer('<Your client_id>:<Your secret_key>').toString('base64'),
    'X-ENVIRONMENT': 'sandbox'
  }}, function (err, res, body) {
    var accessToken = body.accessToken;
    // See below in Quickstart for next steps to fetch report
);

																	


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:

  • accessToken: The access token you can now use to retrieve a Credit Passport® with
  • exp: When the access token will expire, provided as a unix timestamp. Access tokens have a lifetime of 5 minutes. If you do not retrieve the Credit Passport® before the access token expires, you will need to request a new access token.

Example successful response body with access token:

{
  accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MjYwNzc2MDEsImV4cCI6MTUyNjA3NzkwMSwiY2xpZW50X2lkIjoiYWEyZWViZTAtYzAyYS0xMWU2LTg4ZmEtZmJlMzUwZjU4MjBmIiwiZW52Ijoic2FuZGJveCJ9.g1o6uaFedxPeKjV9OL2V5xG3tQfJuvHEtm66mP8LX60",
  exp: 1526077901
}
																	


Step 3: Request a Credit Passport®

Once you have fetched an access token, simply make a GET request to the /connect/passport/v2 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/passport/v2/json.
The PDF endpoint is accessible by sending a GET request to: https://api.neednova.com/connect/passport/v2/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.

Required headers

  • X-ENVIRONMENT: sandbox or production (ensure this matches the environment you have specified in all previous calls)
  • X-PUBLIC-TOKEN: The unique identifier of the Passport you are retrieving, provided to you via webhook
  • Authorization: Bearer Auth, containing the strict base-64 encoded string of the valid accessToken you retrieved in Step 2.

Example request for Credit Passport®


require('request').request({
  url: 'https://api.neednova.com/connect/passport/v2/json',
  method: 'GET',
  headers: {
    Authorization: 'Bearer ' + new Buffer('<valid access token>').toString('base64'),
    'X-ENVIRONMENT': 'sandbox',
    'X-PUBLIC-TOKEN': '812dfac3-ce5a-4da3-843b'
  }}, function (err, res, body) {
    var creditPassportJson = body;
    // See docs.neednova.com for details on 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®:


var request = require('request');
var app = express();

// Add https://your-domain.com/nova as the callback url in the Developer tab of your Nova dashboard
app.post('/nova', function(req, res) {
  const { publicToken, status, userArgs } = req.body; // Full webhook response
  res.status(200).send(); // Send 200 response so Nova knows you received webhook

  if (status === 'NOT_FOUND') {
    console.log('No report found for applicant ' + userArgs);
  } else if (status === 'NOT_AUTHENTICATED') {
    console.log('Applicant' + userArgs + ' not authenticated';
  } else if (status === 'SUCCESS') {
    // Get access token
    request({
      url: 'https://api.neednova.com/connect/accesstoken',
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + new Buffer('<Your client_id>:<Your secret_key>').toString('base64'),
        'X-ENVIRONMENT': 'sandbox'
      }}, function (err, res, body) {
        var accessToken = body.accessToken;

        // Now retrieve Credit Passport
        request({
          url: 'https://api.neednova.com/connect/passport/v2/json',
          method: 'GET',
          headers: {
            Authorization: 'Bearer ' + new Buffer(accessToken).toString('base64'),
            'X-ENVIRONMENT': 'sandbox',
            'X-PUBLIC-TOKEN': publicToken
          }}, function (err, res, body) {
            var creditPassportJson = body;
            // Now we have a Credit Passport for the applicant specified by `userArgs`
            // Store Credit Passport and make credit decision
            // See docs.neednova.com for details on Credit Passport
        );
    );
  } else {
    // Handle errors
    console.log('Unknown Nova status returned');
  }
});

																	

NovaConnect Invite Endpoint

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 headers

  • X-ENVIRONMENT sandbox or production
  • X-PUBLIC-ID Your Nova Credit public_id, found on your dashboard
  • Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key
  • Content-Type application/json

Required body parameters

  • applicantFirstName [string]
  • applicantLastName [string]
  • applicantEmail [string]
  • productId [string] The product_id associated with the product the applicant is applying for
  • userArgs [string] Pass in an identifier for your own records. It will be provided in our webhook call if specified in callbackand in the API JSON response
  • chargeAmount [number] The amount to charge the applicant if a foreign credit report is found, in cents. Only required if you have applicant billing enabled for your customers. See Billing Endpoint
  • currency [string] The currency to charge your customer in. Currently, only USD is supported. Only required if you have applicant billing enabled for your customers. See Billing Endpoint

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.

  • productIdAlias [string] The ID you use internally to identify the product that the applicant is applying for
  • publicIdAlias [string] The ID that you use internally to identify each one of your customer accounts. This is used by resellers and is passed in the body. Where a publicIdAlias is provided, you do not need to pass in X-PUBLIC-ID in the header

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

  • enabledPrefills [array] See below 'Enabling prefilling' for description
  • applicantDateOfBirth [string] The applicant's date of birth, in the format YYYY-MM-DD. This should only be sent if you include it in enabledPrefills
  • applicantSourceCountry [string] Provide an ISO country code to load NovaConnect with a pre-specified country. This must be one of your enabled countries. This should only be sent if you include it in enabledPrefills
  • emailTemplate [string] See below 'Choosing an email template' for description

Enabling prefilling

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:

  • applicantFirstName
  • applicantLastName
  • applicantEmail
  • applicantDateOfBirth
  • applicantSourceCountry

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:

  • INVITE: sends the default 'invite-style' template inviting someone to go through NovaConnect
  • OFFER: sends an 'offer-style' template with conditional approval language and an invitation to go through NovaConnect

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.

Possible responses

  • 200 (Success) The newly created application_id for the invite is returned. This is simply a reference to confirm that the invite was received and sent
  • 403 (Unauthorized) Unauthorized request. Your client_id or secret_key was incorrect, or you did not correctly base-64 encode it
  • 400 (Malformed) Malformed request, headers, or missing required parameters. Error will be one of MALFORMED_HEADERS or MALFORMED_BODY

cURL example request


curl -X POST \
  https://api.neednova.com/connect/invite \
  -H 'Content-Type: application/json' \
  -H 'X-ENVIRONMENT: sandbox' \
  -H 'X-PUBLIC-ID: aa2eebe1-c02a-11e6-88fa-fbe350f5820f' \
  -H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY='
  -d '{
	"applicantFirstName": "Raj",
	"applicantLastName": "Du",
	"applicantEmail": "raj@email.com",
	"applicantSourceCountry": "IND",
	"chargeAmount": 6500,
	"productIdAlias": "3c2da600-17ee-11e8-8a0e-5158039db37e",
	"currency": "USD",
	"userArgs": "custom_id:3c2da600",
	"enabledPrefills": ["applicantFirstName", "applicantLastName", "applicantEmail", "applicantDateOfBirth", "applicantSourceCountry"]
}'

																	


Example response

{
	applicationId: "69de1309-6c0d-42a2-b2f1-3dff5bce10c1"
}
																	

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.

Billing Endpoint

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.

Browser Support

Desktop

  • Google Chrome - fully supported
  • Mozilla Firefox - Versions 29 & up
  • Safari - Versions 8 & up
  • Internet Explorer - Versions 10 & up
  • Opera - Versions 42 & up
  • Microsoft Edge - Versions 14 & up

Mobile

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