Quickstart Guide

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

Embedded Button

Credentials & Identifiers

The NovaConnect and server-side API keys are accessible from your Nova dashboard. Reach out to us at support@novacredit.com to request access 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 minimal code example of how to configure NovaConnect.

<html>
<head>
    <!-- Other head files here -->
    <script src="https://static.novacredit.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: 'your_sandbox_public_id',
          productId: 'your_sandbox_product_id',
        });
    </script>
</body>
</html>

Let's walk through this.
‍
Firstly, you will need to add init.js, a script-tag that should be loaded inside your HTML's <head></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] Any additional metadata you'd like to associate with the report. This will be returned to you in our webhook call and in the API JSON response.
externalId [string] Pass in the unique applicant identifier fom your system. This will be returned to you in our webhook call and in the API JSON response. You can use this identifier to match the Nova public token (Nova report identifier) with the applicant in your system. Note that this MUST be unique and MUST NOT include any consumer PII.
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.
REQUEST_TIMEOUT: The request to the server has timed out.
BUREAU_UNRESPONSIVE: The request to the bureau is nonresponsive.
UNKNOWN_CUSTOMER: The publicId provided does not match a valid customer.
INVALID_PRODUCT: The productId does not match any products for the customer.
DUPLICATE_EXTERNAL_ID: The specified External ID is already in use by another report for the customer.
INTERNAL_ERROR: Nova encountered an error internally.

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.novacredit.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: 'your_sandbox_public_id',
         productId: 'your_sandbox_product_id',
         
         language: 'fr', // Language code
         country: 'IND', // Country code
         userArgs: 'ab-test-123', // Any additional metadata for the report
         externalId: '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 if (error === 'DUPLICATE_EXTERNAL_ID') {
             console.log('ExternalId has already been used in a previous application');
           } 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 webhook callback url in the Nova Credit dashboard via the Developer tab. You can also toggle your event subscriptions on and off there.

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. Only one terminal status outcome is sent per widget open; suppressed outcomes are recorded and attached to the webhook in the history node.

The webhook request will be sent out with the following JSON body:

{
  eventType: 'VISIT',
  status: 'SUCCESS',
  publicToken: '6b986690-458b-11e7-98fb-a71570ea65a6', 
  userArgs: 'user-args', // if present
  externalId: 'internal-applicant-identifier', // if present
  unsupportedCountry: 'AFG', 
  history: [
    {
      eventType: 'SUPPLIER',
      status: 'SUCCESS',
      companyCode: 'IND_CHM',
      dateAttempted: '2019-09-26T32:20:50.52Z' // newest timestamp
    },
    {
      eventType: 'SUPPLIER',
      status: 'NOT_FOUND',
      companyCode: 'IND_CHM',
      dateAttempted: '2019-09-26T32:18:50.53Z' // oldest timestamp, corresponding to the time at which the NovaConnect application was begun
    },
  ] 
}

See full descriptions of the webhook data in our API docs

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

VISIT A single NovaConnect widget interaction, which can consist of multiple suppliers. Only one terminal status outcome is sent per widget open; other supplier-flow outcomes are recorded and attached to the webhook in the history node.
SUPPLIER A specific data supplier flow within a NovaConnect widget interaction

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@novacredit.com with the publicToken.
BUREAU_UNRESPONSIVE* The applicant encountered a bureau outage while going through the widget. They may need to go through NovaConnect again at a later time.
UNSUPPORTED_COUNTRY* The applicant has credit history in a country that is not yet supported. You should make your credit decision without a Credit Passport®

* Indicates that you will not be subscribed to this event by default. You must visit the Developer tab in the Dashboard to subscribe to these events.

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.novacredit.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.novacredit.com/connect/accesstoken',
  method: 'GET',
  headers: {
    Authorization: 'Basic ' + Buffer.from('<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/v4 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:

JSON format
PDF Format: Australia, Brazil, Canada, India, Mexico, Nigeria, South Korea, United Kingdom

The JSON endpoint is accessible by sending a GET request to: https://api.novacredit.com/connect/passport/v4/json.
The PDF endpoint is accessible by sending a GET request to: https://api.novacredit.com/connect/passport/v4/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)
One of the following identifiers:
- X-PUBLIC-TOKEN: The unique identifier of the Passport you are retrieving, provided to you via webhook
- X-EXTERNAL-ID: The passed in unique identifier from your records. It will be provided via webhook call if specified during widget register or application invitation.
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.novacredit.com/connect/passport/v4/json',
  method: 'GET',
  headers: {
    Authorization: 'Bearer ' + Buffer.from('<valid access token>').toString('base64'),
    'X-ENVIRONMENT': 'sandbox',
    'X-PUBLIC-TOKEN': '6b986690-458b-11e7-98fb-a71570ea65a6'
  }}, function (err, res, body) {
    var creditPassportJson = body;
    // See docs.novacredit.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®:

const request = require("request");
const 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) {
  // Full webhook response
  const { publicToken, status, userArgs, externalId } = req.body;

  // Send 200 response so Nova knows you received webhook
  res.status(200).send();

  // Handle success status
  if (status === "SUCCESS") {
    // Get access token
    request({
        url: "https://api.novacredit.com/connect/accesstoken",
        method: "GET",
        headers: {
          Authorization:
            "Basic " + Buffer.from('<Your client_id>:<Your secret_key>').toString("base64"),
            "X-ENVIRONMENT": "sandbox",
        },
      },
      function (err, res, body) {
        const accessToken = body.accessToken;
 
        // Now retrieve Credit Passport
        request({
            url: "https://api.novacredit.com/connect/passport/v4/json", 
            method: "GET",
            headers: {
              Authorization: "Bearer " + Buffer.from(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 `externalId` and `userArgs`
            // Store Credit Passport and make credit decision
            // See docs.novacredit.com for details on Credit Passport
          });
      });
 
    // Handle subscribed error statuses
  } else if (status === "NOT_FOUND") {
    console.log("No report found for applicant " + externalId +  "Metadata: " + userArgs);
  } else if (status === "NOT_AUTHENTICATED") {
    console.log("Applicant " + externalId + " not authenticated. Metadata: " + userArgs);
  } else if (status === "ERROR") {
    console.log("An error occurred while processing " + externalId + " - Please contact support@novacredit.com");
  } else {
    console.log("Unknown Nova status returned");
  }
});

Webhook signatures

Nova Credit optionally signs webhook payloads in order to allow for trust verification of inbound webhook requests. Please contact your Nova Credit account manager to enable this feature. When configured, the webhook request will contain these additional headers:

X-Timestamp Timestamp of request generation
X-Nova-Signature SHA256 HMAC digest of request timestamp and payload, period-delimited. Your webhook signatures secret key is found under the Webhooks section on the Developer tab of your Nova dashboard.

Example verification of signature:

const crypto = require('crypto');

const signature = req.get('X-Nova-Signature');
const timestamp = req.get('X-Timestamp');

const checkPayload = `${timestamp}.${JSON.stringify(req.body)}`;
const checkDigest = crypto.createHmac('sha256', '< webhook signatures secret key >')
    .update(checkPayload)
    .digest('base64');

return crypto.timingSafeEquals(signature, checkDigest);

NovaConnect Suppliers Endpoint

The suppliers endpoint can be used to retrieve a list of active data suppliers for your account. The suppliers endpoint is accessible by sending a GET request to: https://api.novacredit.com/connect/suppliers

Required headers

X-ENVIRONMENT sandbox or production
Authorization Basic Auth, containing the base-64 encoded string of your client_id:secret_key
Content-Type application/json

cURL example request

curl -X GET \
  https://api.novacredit.com/connect/suppliers \
  -H 'Content-Type: application/json' \
  -H 'X-ENVIRONMENT: sandbox' \  
  -H 'Authorization: Basic YWU2Y2VkNjktOGFmOC00N2M5LWE5YTItZjI3NjA4OWI0ZjBlOmY4OGRiNzViODNkOWYwMDhkODJhNTRmOWRkODkwOTdkM2ZkM2Y4OWRlYzFjOTZiMTJkNzFjZjQyNjRhMmE0ZTY=' \

Example response

{
  "suppliers": [
    {
      "countryName": "India",
      "countryCode": "IND",
      "bureauName": "CRIF Highmark",
      "bureauCode": "IND_CHM"
    },
    {
      "countryName": "Mexico",
      "countryCode": "MEX",
      "bureauName": "Circulo de Credito",
      "bureauCode": "MEX_CDC"
    },
    ...
}

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.novacredit.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 callback and 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. When 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

externalId [string] Pass in a unique internal identifier for your own records. It will be provided in our webhook call if specified in callback and in the API JSON response
userArgs [string] Pass in an metadata for your own records. It will be provided in our webhook call if specified in callback and in the API JSON response
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

Managing Multiple Accounts

If you're managing multiple accounts, you can reduce the upfront configuration work by simply passing in the account name and associated product name in the body of the request. To do so, you would add the following two fields.

productName [string] The external name of the product the applicant is applying for. When a productName is provided, you do not need to pass in productId in the body. Note that passing a productName that does not exist will create a new product that the applicant will apply for.
accountName [string] The name of the customer. This is used by resellers and is passed in the body. When an accountName is provided, you do not need to pass in X-PUBLIC-ID in the header, but productName becomes required. Note that passing an accountName that does not exist will create a new account that the applicant will apply for.

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.novacredit.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",
	"externalId": "internal_identifier",
	"enabledPrefills": ["applicantFirstName", "applicantLastName", "applicantEmail", "applicantDateOfBirth", "applicantSourceCountry"]
}'

Example response

{
	applicationId: "69de1309-6c0d-42a2-b2f1-3dff5bce10c1",
	visitId: "5d45a94a-528a-4953-b9b9-51a85e8355a6"
}

NovaConnect Invite Link Endpoint

The invite link endpoint may be used to generate a link that can be provided to an applicant to fill out NovaConnect. The invitation link directs the applicant 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 link 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.novacredit.com/connect/invite-link

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 callback and 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

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. When a publicIdAlias is provided, you do not need to pass in X-PUBLIC-ID in the header

Optional body parameters

Optional body parameters you may include

externalId [string] Pass in a unique internal identifier for your own records. It will be provided in our webhook call if specified in callback and in the API JSON response
userArgs [string] Pass in an metadata for your own records. It will be provided in our webhook call if specified in callback and in the API JSON response
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

Managing Multiple Accounts

productName [string] The external name of the product the applicant is applying for. When a productName is provided, you do not need to pass in productId in the body. Note that passing a productName that does not exist will not create a new product for the applicant to apply for, and will instead return a 400 error.
accountName [string] The name of the customer. This is used by resellers and is passed in the body. When an accountName is provided, you do not need to pass in X-PUBLIC-ID in the header, but productName becomes required. Note that passing an accountName that does not exist will not create a new account for the applicant will apply for, and will instead return a 400 error.

Enabling prefilling

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.

Possible responses

200 (Success) The newly created application_id and visit_id for the invite is returned, along with the generated inviteLink. This invite link may be opened in a new tab or browser, or sent to the applicant.
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.novacredit.com/connect/invite-link \
  -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",
	"externalId": "internal_identifier",
	"enabledPrefills": ["applicantFirstName", "applicantLastName", "applicantEmail", "applicantDateOfBirth", "applicantSourceCountry"]
}'

Example response

{
	applicationId: "69de1309-6c0d-42a2-b2f1-3dff5bce10c1",
	visitId: "5d45a94a-528a-4953-b9b9-51a85e8355a6",
	inviteLink: "https://api.novacredit.com/r/12345"
}

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 - latest versions
Mozilla Firefox - latest versions
Safari - Versions 10 & up
Opera - latest versions
Microsoft Edge - latest versions

Mobile

Include the following script in your HTML's <head></head> tag to ensure that content scales correctly on smaller screens <meta name="viewport" content="width=device-width, initial-scale=1.0">