Quickstart Guide

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 secure plug n' 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 and identifiers

The NovaConnect and server-side API keys are accessible from your Nova dashboard. To request access, use our contact form or login.

Your account keys Programatically generated tokens
  • publicToken: Identifies a specific Nova Credit Passport®
  • accessToken: Used to authorize Nova Credit Passport® requests for server-side integrations (keep this secret!)

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

Step 2: Add NovaConnect to your page
It is recommended that you place the init.js loading script-tag inside your HTML's <head>
The relative order of the div and scripts placements is important.

    <script src="https://static.neednova.com/connect/v2/init.js"></script>

    <!-- Button placement -->
    <div id="nova-button"></div>

          publicId: '40ee75b...',
          env: 'sandbox',
          productId: 'be0f387...',
  • publicId [string]

    See credentials

  • env [string]

    Either 'sandbox' or 'production'.

  • productId [function | string]

    See step 1

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

  • callback [function | string]

    Provide the endpoint as string for Nova to call you when a Nova Credit Passport® is ready.
    Required for server-side integration.

  • userArgs [function | string]

    Pass in an identifier for your own records. It will be provided in our webhook call if specified in callback and in the API JSON response.

  • 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
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: Get an access token

To get an accessToken, make a request to /connect/accesstoken using your credentials.

    curl https://api.neednova.com/connect/accesstoken \
    -H "X-ENVIRONMENT: sandbox" \
    -H "Authorization: Basic $(echo -n '<Your client_id>:<Your secret_key>' | openssl base64 -A)"


      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;


Only request a new accessToken once the one you currently have is expired

Step 2: 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. Set up a POST webhook and add the endpoint as the callback parameter to your NovaConnect integration. For an overview of the codes see our API docs. You will need this information in the next step.

    // Add https://your-domain.com/nova as a callback parameter to NovaConnect
    var app = express();
    app.post('/nova', function(req, res) {
      var public_token = req.body.publicToken;
      var status = req.body.status;

      if (status === 'SUCCESS') {
        // Get access token and retrieve report
      } else {
        // Handle errors


Step 3: Request a Nova Credit Passport®

To get a Nova Credit Passport®, simply make a GET request to the /connect/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

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


      url: 'https://api.neednova.com/connect/passport/json',
      method: 'GET',
      headers: {
        Authorization: 'Bearer ' + new Buffer('<A valid access token>').toString('base64'),
        'X-PUBLIC-TOKEN': '93e3d55...',
        'X-ENVIRONMENT': 'sandbox'
    function (err, res, body) {
      var passportData = body;


Browser support


Fully supported

Versions 29 & up

Versions 8 & up

Versions 10 & up

Versions 42 & up

Versions 14 & up


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

Integrate in under 5 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.