Credit Applications

Prerequisites

Before diving into the integration process, ensure you have the following:

Sign up for a Drivly account
Create a DRIVLY_API_KEY
Have a basic understanding of REST APIs
A secure environment for handling sensitive data

Always perform Credit Application operations server-side to secure API keys.

Overview

The Credit Application process enables users to secure auto loans, providing them with information on loan amounts and interest rates. This guide covers various scenarios, including applications for primary applicants and co-applicants, with or without trade-ins.

Implementation Options

You can implement the Credit Application API using either the Drivly SDK or the API:

Drivly SDK

Follow the steps below to set up using the SDK.

To get started, you will need to install the Drivly SDK.

yarn add @drivly/commerce

Create a singleton instance of the SDK.

We will use the DRIVLY_API_KEY and will start in sandbox.

sdk.ts

import { SDK } from '@drivly/commerce'

export const sdk = SDK({
  apiKey: process.env.DRIVLY_API_KEY as string,
  environment: 'sandbox',
})

Now, we can export the sdk to use in our application

Make a function to CREATE the Credit Application.

credit.action.ts

'use server' // Next JS specific for server actions

import { CreditApplication } from '@drivly/commerce'
import { sdk } from './sdk'

type CreditData = Omit<CreditApplication, 'id' | 'createdAt' | 'updatedAt'>

export const createCreditApp = async (data: CreditData) => {
  try {
    // Change to 'Production' for live applications
    const environment = 'Development'

    const result = await sdk?.commerce.creditApplications.create({
      doc: { environment, ...data },
    })

    console.log(result)
  } catch (error) {
    console.error(error)
  }
}

We might need to CREATE a Trade, we will need a few more functions.

In cases where a trade-in is involved, we need to create a trade record for the vehicle being traded.

'use server' // Next JS specific for server actions

import { sdk } from './sdk'
import { createLienholder, getLienholderId } from './lienholder.action'
import { CreateTradeParams } from './shared.param.types'
import { createCommerceVehicle, getCommerceVehicleId } from './vehicle.action'

export const createTrade = (params: CreateTradeParams) => {
  try {
    const { data, id: creditApplication } = params
    const { lienholder: companyName, payoff, odometer, ...rest } = data
    let lienholder: string | undefined

    if (companyName) {
      const prevLien = await getLienholderId({ companyName })

      lienholder =
        prevLien !== 'Lienholder not found'
          ? prevLien
          : await createLienholder({ data: { companyName } })
    }

    const prevVehicleId = await getCommerceVehicleId(rest.vin as string)

    const vehicle =
      prevVehicleId !== 'Vehicle not found'
        ? prevVehicleId
        : await createCommerceVehicle({ data: rest })

    if (vehicle === 'Failed to create vehicle') throw new Error(vehicle)
    if (lienholder === 'Lienholder not created') throw new Error(lienholder)

    const result = await sdk?.commerce.trades.create({
      doc: {
        creditApplication, // Credit Application ID
        lienholder, // Lienholder ID
        odometer,
        tradeInPayoffBalance: payoff,
        vehicle, // Vehicle ID
      },
      depth: 0,
    })

    if (!result) throw new Error('Trade not created')

    return result.doc.id
  } catch (error) {
    console.error(error)
  }
}

Use the API

We can use https://commerce.driv.ly/api/creditApplications to create and manage Credit Applications.

Create an environment variable for your API Key.

.env

DRIVLY_API_KEY='YOUR_API_KEY'

Make a function to CREATE the Credit Application.

credit.action.ts

import { CreditApplication } from '@drivly/commerce'

type CreditData = Omit<CreditApplication, 'id' | 'createdAt' | 'updatedAt'>

const url = 'https://commerce.driv.ly/api/creditApplications'

export const createCreditApp = async (data: CreditData) => {
  try {
    // Change to 'Production' for live applications
    const environment = 'Development'

    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `${process.env.DRIVLY_API_KEY}`,
      },
      body: JSON.stringify({ environment, ...data }),
    }).then((res) => res.json())

    console.log(response)
  } catch (error) {
    console.error(error)
  }
}

We might need to CREATE a Trade, we will need a few more functions.

In cases where a trade-in is involved, we need to create a trade record for the vehicle being traded.

import { createLienholder, getLienholderId } from './lienholder.action'
import { CreateTradeParams } from './shared.param.types'
import { createCommerceVehicle, getCommerceVehicleId } from './vehicle.action'

const url = 'https://commerce.driv.ly/api/trades'

export const createTrade = (params: CreateTradeParams) => {
  try {
    const { data, id: creditApplication } = params
    const { lienholder: companyName, payoff, odometer, ...rest } = data
    let lienholder: string | undefined

    if (companyName) {
      const prevLien = await getLienholderId({ companyName })

      lienholder =
        prevLien !== 'Lienholder not found'
          ? prevLien
          : await createLienholder({ data: { companyName } })
    }

    const prevVehicleId = await getCommerceVehicleId(rest.vin as string)

    const vehicle =
      prevVehicleId !== 'Vehicle not found'
        ? prevVehicleId
        : await createCommerceVehicle({ data: rest })

    if (vehicle === 'Failed to create vehicle') throw new Error(vehicle)
    if (lienholder === 'Lienholder not created') throw new Error(lienholder)

    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `${process.env.DRIVLY_API_KEY}`,
      },
      body: JSON.stringify({
        creditApplication, // Credit Application ID
        lienholder, // Lienholder ID
        odometer,
        tradeInPayoffBalance: payoff,
        vehicle, // Vehicle ID
      }),
    }).then((res) => res.json())

    if (!response?.doc) throw new Error('Trade not created')

    return response.doc.id
  } catch (error) {
    console.error(error)
  }
}

Handling Use Cases

The following scenarios will cover various Credit Application use cases including primary applicants, co-applicants, and trade-ins.

Primary Applicant

Danny found the car of his dreams. He wants to secure a loan to buy the car. He goes to your website and fills out a form to find out how much of a loan he can secure.

When a user, such as Danny, wishes to secure a loan for his dream car, follow these steps:

Direct the user to the Credit Application Form on your Website.

Make sure the form includes fields for the primary applicant’s personal, residence, employment, and vehicle information.

Also include fields for the application type, finance amount, pre-approval ID and has co-applicant.

primaryApplicant

Applicant Object

Applicant Properties

firstName

string

lastName

string

birthDate

string

emailAddress

string

cellPhone

string

ssn

string

relationshipType

enum<string> | null

Available options: SPOUSE, RELATIVE, FRIEND, or null (for primary applicant)

currentResidence | previousResidence

Residence Object

If current monthsAtResidence < 24, previousResidence is REQUIRED

Residence Properties

monthlyPaymentAmount

number

monthsAtResidence

number

ownershipStatus

enum<string>

Available options: RENT, OWN, RELATIVE_OWNED

address

Address Object

Address Properties

lineOne

string

lineTwo

string

city

string

state

enum<string>

Available options: AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY

postalCode

string

currentEmployment | previousEmployment

Employment Object

If currentEmployment monthsAtEmployer < 24, previousEmployment is REQUIRED

Employment Properties

yearlyIncomeAmount

number

monthsAtEmployer

number

employmentType

enum<string>

Available options: FULL_TIME, PART_TIME, SELF_EMPLOYED, UNEMPLOYED, RETIRED

employerName

string

employmentPosition

string

employmentAddress

Address Object

Address Properties

lineOne

string

lineTwo

string

city

string

state

enum<string>

postalCode

string

additionalIncomeAmount

number | null

additionalIncomeFrequency

enum<string> | null

Available options: WEEKLY, BI_WEEKLY, TWICE_MONTHLY, MONTHLY, YEARLY

additionalIncomeSource

string | null

terms

Terms Object

Terms Properties

agreeToTerms

boolean

agreeIP

string

agreeUserAgent

string

vehicle

Vehicle Object

Vehicle Properties

vin

string

year

number

make

string

model

string

trim

string

mileage

number

lien

Lien Object

Lien Properties

lienHolder

string | null

monthlyPaymentAmount

number | null

payoffAmount

number | null

initialTerm

number | null

remainingTerm

number | null

originalAmount

number | null

apr

number | null

applicationType

enum<string>

Available options: PURCHASE, REFINANCE, LEASE_BUYOUT

hasCoApplicant

boolean

financeAmount

number

preApproval

string

Format your Request Body

Before sending the request, we need to include the following fields in the request body:

sendTo: The recipient of the application. Available options: RouteOne, TSG
state: Set to DRAFT in order to create a new application for processing.
environment: The application can be submitted in Production or Development

Example Data

const creditData = {
  sendTo: 'RouteOne',
  state: 'DRAFT',
  environment: 'Production',
  applicationType: 'REFINANCE',
  financeAmount: 65000,
  downPayment: 5000,
  preApproval: '123456',
  primaryApplicant: {
    firstName: 'Danny',
    lastName: 'Turner',
    birthDate: '06/24/1995',
    emailAddress: 'dannyt@gmail.com',
    cellPhone: '561-555-1212',
    ssn: '555-55-5555',
    currentResidence: {
      monthlyPaymentAmount: 3000,
      monthsAtResidence: 36,
      ownershipStatus: 'OWN',
      address: {
        lineOne: '123 Ocean Drive',
        lineTwo: 'Apt 2',
        city: 'Juno Beach',
        state: 'FL',
        postalCode: '33408',
      },
    },
    currentEmployment: {
      yearlyIncomeAmount: 100000,
      monthsAtEmployer: 48,
      employmentType: 'FULL_TIME',
      employerName: 'Loggerhead Marine Life Center',
      employmentPosition: 'Marine Biologist',
      employmentAddress: {
        lineOne: '14200 US-1',
        lineTwo: 'Suite 100',
        city: 'Juno Beach',
        state: 'FL',
        postalCode: '33408',
      },
    },
    terms: {
      agreeToTerms: true,
      agreeIP: '150.80.15.220',
      agreeUserAgent: 'Mozilla/5.0',
    },
  },
  hasCoApplicant: false,
  vehicle: {
    vin: 'W1NKM4HB4RF139674',
    year: 2024,
    make: 'Mercedes-Benz',
    model: 'GLC',
    trim: 'GLC 300 4MATIC',
    mileage: 20,
    lien: {
      lienHolder: null,
      monthlyPaymentAmount: null,
      payoffAmount: null,
      initialTerm: null,
      remainingTerm: null,
      originalAmount: null,
      apr: null,
    },
  },
}

Send the Request.

Now that we have the data formatted, we can send the request to create the Credit Application.

import { createCreditApp } from './credit.action'

const creditAppId = await createCreditApp(creditData)
console.log(creditAppId)

Always perform Credit Application operations server-side to secure API keys.

Primary and CoApplicant

Danny’s wife Michelle found a car she loves. They want to secure a loan to buy the car. They go to your website and fill out a form to find out how much of a loan they can secure.

When both Danny and Michelle want to secure a loan for a car they love, their journey through your website will be slightly different to account for the additional information needed from the co-applicant. Here’s how to guide them:

Direct Both Applicants to the Credit Application Form.

Ensure your form is set up to handle input from both the primary applicant and the co-applicant. It’s crucial to clearly label which sections pertain to each applicant to avoid confusion.

Include identical fields for both the primary applicant and the co-applicant.

Collect and Format Data for Both Applicants.

While collecting the data, remember to gather information from both Danny and Michelle, treating Michelle’s data as the coApplicant’s or vice-versa. The data structure for the coApplicant will mirror that of the primaryApplicant.

For the relationshipType in the coApplicant’s data, select the appropriate option that describes their relationship to the primary applicant.

Format Data

const creditData = {
  sendTo: 'RouteOne',
  state: 'DRAFT',
  environment: 'Production',
  // Previous fields for primaryApplicant
  coApplicant: {
    // Repeat the fields from primaryApplicant,
    // filling in Michelle's information
  },
  hasCoApplicant: true,
  // Other necessary fields (vehicle, applicationType, etc.)
}

Send the Request.

Now that we have the data formatted, we can send the request to create the Credit Application.

import { createCreditApp } from './credit.action'

const creditAppId = await createCreditApp(creditData)
console.log(creditAppId)

Always perform Credit Application operations server-side to secure API keys.

Primary with Trade

Danny is looking to trade-in his 2011 Lincoln Town Car for a 2023 Genesis G80. He wants to secure a loan to buy the car and trade-in his old car. He goes to your website and fills out a form to find out how much of a loan he can secure.

In cases where Danny is looking to trade in his current vehicle as part of securing a new loan, the process involves an additional step to include trade-in information.

Guide Danny to the Enhanced Credit Application Form.

Adjust your form to include a section for vehicle trade-in details.

tradeInVehicle

Trade-In Object

Trade-In Properties

vin

string

year

string

make

string

model

string

trim

string

odometer

number

payoff

string

lienholder

string

Ensure the form includes fields for the primary applicant’s personal, residence, employment, and vehicle information.

Collect Information Including Trade-In Details.

Apart from collecting the standard application information, you’ll need to gather details about the vehicle Danny intends to trade.

tradeInData

const tradeInDetails = {
  make: 'Lincoln',
  model: 'Town Car',
  year: '2011',
  payoff: '7000',
  // Additional fields as necessary
}

Create a Trade.

Before sending the Credit Application, you’ll need to create a trade-in record for Danny’s vehicle.

import { createTrade } from './trade.action'

const tradeInId = await createTrade(tradeInDetails)
console.log(tradeInId)

Always perform Credit Application operations server-side to secure API keys.

Send the Request with the tradeInId

const creditData = {
  sendTo: 'RouteOne',
  state: 'DRAFT',
  environment: 'Production',
  applicationType: 'PURCHASE',
  financeAmount: 65000,
  downPayment: 5000,
  primaryApplicant: {
    // Primary applicant data
  },
  vehicle: {
    // Vehicle data
  },
  trades: [tradeInId],
}

const creditAppId = await createCreditApp(creditData)
console.log(creditAppId)

Primary and CoApplicant with Trade

Danny and Michelle are looking to trade-in their 2011 Lincoln Town Car for a 2023 Genesis G80. They want to secure a loan to buy the car and trade-in their old car. They go to your website and fill out a form to find out how much of a loan they can secure.

For scenarios involving both a primary and a co-applicant intending to trade in a vehicle, combine the steps and considerations from the previous scenarios.

Guide Both Applicants to the Enhanced Credit Application Form.

Ensure your form includes sections for both applicants and trade-in details. Ensure clarity and ease of navigation within the form.

Collect Information Including Trade-In Details.

Gather information from both Danny and Michelle, including details about the vehicle they intend to trade.

Create a Trade.

Before sending the Credit Application, create a trade-in record for the vehicle Danny and Michelle intend to trade.

import { createTrade } from './trade.action'

const tradeInId = await createTrade(tradeInDetails)
console.log(tradeInId)

Send the Request with the tradeInId

const creditData = {
  sendTo: 'RouteOne',
  state: 'DRAFT',
  environment: 'Production',
  applicationType: 'PURCHASE',
  financeAmount: 65000,
  downPayment: 5000,
  primaryApplicant: {
    // Primary applicant data
  },
  coApplicant: {
    // Co-applicant data
  },
  vehicle: {
    // Vehicle data
  },
  trades: [tradeInId],
}

const creditAppId = await createCreditApp(creditData)
console.log(creditAppId)

Conclusion

Congratulations! You’ve successfully integrated Credit Applications into your platform. By following this guide, you’ve learned how to handle various scenarios, including primary applicants, co-applicants, and trade-ins. You’re now equipped to provide a seamless experience for users looking to secure auto loans. If you have any questions or need further assistance, please don’t hesitate to reach out to our support team. Happy coding!

Next Steps

Ready to get started with Credit Applications?

Credit Application API Reference

Explore the Credit Application API to find, create, and manage credit applications.

Services

Guides

API Reference

Prerequisites

Overview

Implementation Options

Handling Use Cases

Primary Applicant

Primary and CoApplicant

Primary with Trade

Primary and CoApplicant with Trade

Conclusion

Next Steps

Credit Application API Reference

Services

Guides

API Reference

​Prerequisites

​Overview

​Implementation Options

​Handling Use Cases

​Primary Applicant

​Primary and CoApplicant

​Primary with Trade

​Primary and CoApplicant with Trade

​Conclusion

​Next Steps

Credit Application API Reference

Prerequisites

Overview

Implementation Options

Handling Use Cases

Primary Applicant

Primary and CoApplicant

Primary with Trade

Primary and CoApplicant with Trade

Conclusion

Next Steps