> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driv.ly/llms.txt
> Use this file to discover all available pages before exploring further.
# Credit Applications
> Get started with Credit Applications with our step-by-step guide.
export const HeroContent = ({children, withGrid}) =>
{withGrid &&
}
{children}
;
export const StoryBoard = ({children}) => ;
export const CustomCallout = ({children, variant, icon}) => <>
{variant === 'tip' && }
{variant === 'note' && }
{variant === 'info' && }
{variant === 'warning' && }
{variant === 'check' && }
;
## Prerequisites
Before diving into the integration process, ensure you have the following:
1. [Sign up](https://drivly.typeform.com/applyforaccess) for a Drivly account
2. Create a [DRIVLY\_API\_KEY](/developers/auth)
3. Have a basic understanding of REST APIs
4. 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:
Follow the steps below to set up using the SDK.
```bash Yarn theme={null}
yarn add @drivly/commerce
```
```bash NPM theme={null}
npm install @drivly/commerce
```
```bash PnPM theme={null}
pnpm install @drivly/commerce
```
```bash Bun theme={null}
bun add @drivly/commerce
```
```bash CDN theme={null}
```
{' '}
We will use the `DRIVLY_API_KEY` and will start in `sandbox`.
```javascript sdk.ts theme={null}
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
```javascript credit.action.ts theme={null}
'use server' // Next JS specific for server actions
import { CreditApplication } from '@drivly/commerce'
import { sdk } from './sdk'
type CreditData = Omit
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)
}
}
```
In cases where a trade-in is involved, we need to create a trade record for the vehicle being traded.
```javascript trade.action.ts theme={null}
'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)
}
}
```
```javascript lienholder.action.ts theme={null}
'use server' // Next JS specific for server actions
import { sdk } from '../sdk'
import { CreateLienholderParams, GetLienholderParams } from './shared.param.types'
export async function createLienholder(params: CreateLienholderParams) {
try {
const {
data: { companyName, companyType = ['Lender'] },
} = params
const result = await sdk?.commerce.customers.create({
doc: { companyName, companyType },
})
if (!result?.doc) throw new Error('Lienholder not created')
return result.doc.id
} catch (error) {
console.error(error)
}
}
export async function getLienholderId(params: GetLienholderParams) {
try {
const { companyName } = params
const result = await sdk?.commerce.customers.find({
where: { companyName: { equals: companyName } },
})
if (!result?.docs?.[0]) throw new Error('Lienholder not found')
return result.docs[0].id
} catch (error) {
console.error(error)
}
}
```
```javascript vehicle.action.ts theme={null}
'use server' // Next JS specific for server actions
import { sdk } from '../sdk'
import { CreateCommerceVehicleParams } from './shared.param.types'
export async function getCommerceVehicleId(vin: string) {
try {
const result = await sdk?.commerce.vehicles.find({
where: { vin: { equals: vin } },
})
if (!result?.docs?.[0]?.id) throw new Error('Vehicle not found')
return result.docs[0].id
} catch (error) {
console.error(error)
}
}
export async function createCommerceVehicle(params: CreateCommerceVehicleParams) {
try {
const { data } = params
const result = await sdk?.commerce.vehicles.create({ doc: data })
if (!result) throw new Error('Failed to create vehicle')
return result.doc.id
} catch (error) {
console.error(error)
}
}
```
```typescript shared.param.types.ts theme={null}
import { Customer } from '@drivly/commerce'
export interface CreateCommerceVehicleParams {
data: {
vin?: string | undefined
year?: string | undefined
make?: string | undefined
model?: string | undefined
trim?: string | undefined
}
}
export interface CreateTradeParams {
id: string
data: {
vin?: string | undefined
year?: string | undefined
make?: string | undefined
model?: string | undefined
trim?: string | undefined
odometer?: number | undefined
payoff?: string | undefined
lienholder?: string | undefined
}
}
export interface CreateLienholderParams {
data: Omit
}
export interface GetLienholderParams {
companyName: string
}
```
We can use `https://commerce.driv.ly/api/creditApplications` to create and manage Credit Applications.
```bash .env theme={null}
DRIVLY_API_KEY='YOUR_API_KEY'
```
```javascript credit.action.ts theme={null}
import { CreditApplication } from '@drivly/commerce'
type CreditData = Omit
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)
}
}
```
In cases where a trade-in is involved, we need to create a trade record for the vehicle being traded.
```javascript trade.action.ts theme={null}
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)
}
}
```
```javascript lienholder.action.ts theme={null}
import { CreateLienholderParams, GetLienholderParams } from './shared.param.types'
const url = 'https://commerce.driv.ly/api/customers'
export async function createLienholder(params: CreateLienholderParams) {
try {
const {
data: { companyName, companyType = ['Lender'] },
} = params
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `${process.env.DRIVLY_API_KEY}`,
},
body: JSON.stringify({ companyName, companyType }),
}).then((res) => res.json())
if (!response?.doc) throw new Error('Lienholder not created')
return response.doc.id
} catch (error) {
console.error(error)
}
}
export async function getLienholderId(params: GetLienholderParams) {
try {
const { companyName } = params
const response = await fetch(`${url}?where[companyName][equals]=${companyName}`, {
method: 'GET',
headers: {
'Content-Type': 'application/json',
Authorization: `${process.env.DRIVLY_API_KEY}`,
},
}).then((res) => res.json())
if (!response?.docs?.[0]) throw new Error('Lienholder not found')
return response.docs[0].id
} catch (error) {
console.error(error)
}
}
```
```javascript vehicle.action.ts theme={null}
import { CreateCommerceVehicleParams } from './shared.param.types'
const url = 'https://commerce.driv.ly/api/vehicles'
export async function getCommerceVehicleId(vin: string) {
try {
const response = await fetch(`${url}?where[vin][equals]=${vin}`, {
method: 'GET',
headers: {
'Content-Type': 'application/json',
Authorization: `${process.env.DRIVLY_API_KEY}`,
},
}).then((res) => res.json())
if (!response?.docs?.[0]) throw new Error('Vehicle not found')
return response.docs[0].id
} catch (error) {
console.error(error)
}
}
export async function createCommerceVehicle(params: CreateCommerceVehicleParams) {
try {
const { data } = params
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `${process.env.DRIVLY_API_KEY}`,
},
body: JSON.stringify(data),
}).then((res) => res.json())
if (!response?.doc) throw new Error('Failed to create vehicle')
return response.doc.id
} catch (error) {
console.error(error)
}
}
```
```typescript shared.param.types.ts theme={null}
import { Customer } from '@drivly/commerce'
export interface CreateCommerceVehicleParams {
data: {
vin?: string | undefined
year?: string | undefined
make?: string | undefined
model?: string | undefined
trim?: string | undefined
}
}
export interface CreateTradeParams {
id: string
data: {
vin?: string | undefined
year?: string | undefined
make?: string | undefined
model?: string | undefined
trim?: string | undefined
odometer?: number | undefined
payoff?: string | undefined
lienholder?: string | undefined
}
}
export interface CreateLienholderParams {
data: Omit
}
export interface GetLienholderParams {
companyName: string
}
```
***
## 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:
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.
Available options: `SPOUSE`, `RELATIVE`, `FRIEND`, or `null` (for primary applicant)
If current monthsAtResidence \< 24, previousResidence is REQUIRED
Available options: `RENT`, `OWN`, `RELATIVE_OWNED`
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`, O`H`, `OK`, `OR`, `PA`, `RI`,
`SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`, `WA`, `WV`, `WI`, `WY`
If currentEmployment monthsAtEmployer \< 24, previousEmployment is REQUIRED
Available options: `FULL_TIME`, `PART_TIME`, `SELF_EMPLOYED`, `UNEMPLOYED`, `RETIRED`
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`, O`H`, `OK`, `OR`, `PA`, `RI`,
`SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`, `WA`, `WV`, `WI`, `WY`
Available options: `WEEKLY`, `BI_WEEKLY`, `TWICE_MONTHLY`, `MONTHLY`, `YEARLY`
Available options: `PURCHASE`, `REFINANCE`, `LEASE_BUYOUT`
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`
```javascript Example Data theme={null}
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,
},
},
}
```
Now that we have the data formatted, we can send the request to create the Credit Application.
```javascript theme={null}
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:
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.
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.
```javascript Format Data theme={null}
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.)
}
```
Now that we have the data formatted, we can send the request to create the Credit Application.
```javascript theme={null}
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.
Adjust your form to include a section for vehicle trade-in details.
Ensure the form includes fields for the primary applicant's personal, residence, employment, and vehicle information.
Apart from collecting the standard application information, you'll need to gather details about the vehicle Danny intends to trade.
```javascript tradeInData theme={null}
const tradeInDetails = {
make: 'Lincoln',
model: 'Town Car',
year: '2011',
payoff: '7000',
// Additional fields as necessary
}
```
Before sending the Credit Application, you'll need to create a trade-in record for Danny's vehicle.
```javascript theme={null}
import { createTrade } from './trade.action'
const tradeInId = await createTrade(tradeInDetails)
console.log(tradeInId)
```
Always perform Credit Application operations server-side to secure API keys.
```javascript theme={null}
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.
Ensure your form includes sections for both applicants and trade-in details. Ensure clarity and ease of navigation within the form.
Gather information from both Danny and Michelle, including details about the vehicle they intend to trade.
Before sending the Credit Application, create a trade-in record for the vehicle Danny and Michelle intend to trade.
```javascript theme={null}
import { createTrade } from './trade.action'
const tradeInId = await createTrade(tradeInDetails)
console.log(tradeInId)
```
```javascript theme={null}
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](mailto:sales@driv.ly). Happy coding!
***
## Next Steps
Ready to get started with Credit Applications?
Explore the Credit Application API to find, create, and manage credit applications.