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 Nova 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 Nova 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 clicking on the Nova button (web & mobile compatible):

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 Nova Credit Passport®
  • accessToken: Used to authorize Nova Credit Passport® requests for server-side integrations (keep this secret). You will use this token to programmatically fetch Nova 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.

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

It is recommended that you place the init.js loading script-tag inside your HTML's <head>. Place the nova-button div where you would like the NovaConnect button to appear, and place the script that registers the Nova window at the bottom of your HTML body. The relative order of the div and scripts placements is important. Here's an example HTML file:

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

    <script>
        window.Nova.register({
          publicId: '40ee75b...',
          env: 'sandbox',
          productId: 'be0f387...',
        });
    </script>
</body>
</html>
                                


NovaConnect Register Parameters

You can dynamically set values if you pass a function to any suitable parameter but make sure to resolve with the right type.

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 4: Customize NovaConnect (optional)
Additional parameters

  • onSuccess [function] Called with arguments (publicToken, status) when an applicant successfully completes the NovaConnect flow.
  • onError [function] Called with arguments (publicToken, error) when an unexpected error occurs.
  • onExit [function] Called when the applicant closes NovaConnect voluntarily.
  • country [function | string] Provide an ISO country code to load NovaConnect with a pre-specified country.
  • userArgs [function | string] Pass in an identifier for your own records. It will be provided in our webhook call and in the API JSON response. This is most commonly your own user identifier.
  • prefill [function | object] Prefill specific NovaConnect form fields for the applicant by passing an object which maps keys to string values.
  • hideButton [boolean] Use a custom button instead of the default Nova button. To display NovaConnect call window.Nova.fire().

Prefill keys

  • 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
  • country The country the widget should automatically open to

onSuccess status codes

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

onError error types

  • RequestTimeoutError
  • UnauthorizedError
  • IntegrationError
  • InternalError

Server-Side Integration

Step 1: Set-up your webhook

Once an applicant has finished the NovaConnect flow, Nova can automatically call your provided callback to update you on the status of the Nova Credit Passport® tied to the publicToken.

You can set your callback in the Nova Credit dashboard via the Developer tab. For an overview of the codes see our API docs. You will need this information in the next step.

Here's an example of how to define a route for the callback url using NodeJS and Express:


    // Add https://your-domain.com/nova as the callback url in the Developer tab of your Nova dashboard
    var app = express();
    app.post('/nova', function(req, res) {
      const { publicToken, status, userArgs } = req.body; // The full response
      var public_token = publicToken; // The identifier of the Passport
      var status = req.body.status;

      if (status === 'SUCCESS') {
        // Get access token and retrieve report
      } else {
        // Handle errors
      }
      res.status(200).send();
    });

																	


Step 2: Get an access token

To get an accessToken, make a request to /connect/accesstoken using your credentials. You will use this accessToken to access your customer's Nova Credit Passports®.

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 base-64 encoded string of your client_id:secret_key

Example request


    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;
    });

																	


Example response

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

 Only request a new accessToken once the one you currently have is expired. The response includes the accessToken's expiration date as a unix timestamp.


Step 3: Request a Nova Credit Passport®

Once you have received a webhook that the Passport is ready, simply make a GET request to the /connect/v2/passport endpoints using the accessToken that you obtained in the previous step. Make sure to encode the accessToken using base 64.

Nova Credit Passport® format examples

The passport endpoint is accessible by sending a GET request to: https://api.neednova.com/connect/v2/passport/json

Required headers

  • X-ENVIRONMENT sandbox or production
  • X-PUBLIC-TOKEN The unique identifier of the Passport you are retrieving, sent to you via webhook
  • Authorization Bearer Auth, containing the base-64 encoded string of a valid accessToken

cURL example request


    curl https://api.neednova.com/connect/passport/v2/json \
    -H "X-ENVIRONMENT: sandbox" \
    -H "X-PUBLIC-TOKEN: 93e3d55..." \
    -H "Authorization: Bearer $(echo -n <A valid access token> | openssl base64 -A)"

																	

View our API reference for sample responses.

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