Skip to main content

F&I data model

This is the data structure of the F&I request body when you are sending F&I data to myKaarma.

The endpoint expects a top-level request object with type: "F&I" and the actual F&I deal under the payload object.

Validation Rules

  • type is required and must be F&I.
  • payload.uuid is required.
  • payload.dealerUuid is required.
  • payload.customer is required.
  • payload.customer.customerKey is required.
  • payload.customer.lastName is required if payload.customer.isBusiness is false or null.
  • payload.customer.company is required if payload.customer.isBusiness is true.
  • payload.vehicle.vehicleKey is required if payload.vehicle is not null.
  • Each phoneNumber must be exactly 12 characters if payload.customer.phoneNumbers is sent.
  • All other fields in the current F&I schema are optional.

Summary of the fields

Top-level request fields

Parameter NameDescription
typeEvent type for the request. Must be F&I.
payloadContainer object holding the F&I deal data.
payload.uuidUnique identifier for the incoming F&I event.
payload.dealerUuidmyKaarma dealer UUID for the event.
payload.vehiclePrimary vehicle information for the F&I deal.
payload.customerPrimary customer information for the F&I deal.
payload.coBuyerCo-buyer information for the F&I deal.
payload.dealDeal-level metadata and lifecycle information.
payload.pricingVehicle pricing values for the deal.
payload.profitGross, commission, and F&I income values.
payload.financingFinancing structure, rates, payments, and down payment values.
payload.leaseLease-specific values for the deal.
payload.taxesTax summary and tax line details.
payload.feesFee summary and fee line details.
payload.weOwesWe-owe and residual totals associated with the deal.
payload.insuranceInsurance, warranty, mechanical breakdown insurance (MBI), accident and health (AH), credit life (CL), and related product data.
payload.trades[]List of trade-in vehicles.
payload.tradeTotalsAggregated totals for all trades.
payload.lienHolderLien holder details for the transaction.
payload.salesTeamSales, F&I, CRM, and delivery team assignments.
payload.commissionsDetailed commission, sale credit, and spiff values.
payload.tradeDealerDefined[]List of trade-specific dealer-defined custom fields.
payload.dealerDefined[]List of deal-level dealer-defined custom fields.
payload.fiAux[]List of auxiliary F&I fields from the source DMS.
payload.pickupPickup date and pickup pay values.
payload.miscellaneous[]List of miscellaneous fields.
payload.mileageExpectedExpected lease or contract mileage value.
payload.mileagePenaltyAmountMileage penalty amount value.
payload.mileagePenaltyRateMileage penalty rate value.

payload.vehicle object

Parameter NameDescriptionField Length
payload.vehicle.vinVIN of the primary vehicle in the deal.17
payload.vehicle.vehicleKeySource-system key for the vehicle.-
payload.vehicle.vehicleUuidmyKaarma or external UUID for the vehicle.-
payload.vehicle.vehicleMakeVehicle make.100
payload.vehicle.vehicleModelVehicle model.45
payload.vehicle.vehicleYearVehicle year.4
payload.vehicle.vehicleTrimVehicle trim.100
payload.vehicle.vehicleEngineVehicle engine description.300
payload.vehicle.colorVehicle color.100
payload.vehicle.bodyStyleVehicle body style.-
payload.vehicle.licensePlateVehicle license plate.20
payload.vehicle.estimatedMileageEstimated vehicle mileage.30
payload.vehicle.stockNumberDealer stock number for the vehicle.-
payload.vehicle.msrpVehicle MSRP value.-

Customer, CoBuyer, Lien Holder object

For the table below, ParentEntity can refer to customer, coBuyer, or lienHolder.

Parameter NameDescriptionField Length
payload.ParentEntity.customerUuidmyKaarma or external UUID for the customer, co-buyer, or lien holder.-
payload.ParentEntity.customerKeySource-system key for the customer, co-buyer, or lien holder.45
payload.ParentEntity.firstNameFirst name for the customer, co-buyer, or lien holder.100
payload.ParentEntity.middleNameMiddle name for the customer, co-buyer, or lien holder.-
payload.ParentEntity.lastNameLast name for the customer, co-buyer, or lien holder.100
payload.ParentEntity.companyCompany name for a business customer, co-buyer, or lien holder.100
payload.ParentEntity.isBusinessIndicates whether the customer, co-buyer, or lien holder is a business.1
payload.ParentEntity.preferredLocalePreferred locale for the customer, co-buyer, or lien holder.20
payload.ParentEntity.assignedSAAssigned service advisor or sales associate identifier.-
payload.ParentEntity.commentsComments associated with the customer, co-buyer, or lien holder.-
payload.ParentEntity.emailsList of email addresses for the customer, co-buyer, or lien holder.-
payload.ParentEntity.phoneNumbersList of phone numbers for the customer, co-buyer, or lien holder.-
payload.ParentEntity.addressesList of addresses for the customer, co-buyer, or lien holder.-

Customer, CoBuyer, Lien Holder object

For the table below, ParentEntity can refer to customer, coBuyer, or lienHolder.

Parameter NameDescriptionField Length
payload.ParentEntity.emails[].emailAddressEmail address for the customer, co-buyer, or lien holder.100
payload.ParentEntity.emails[].labelLabel for the email address.-
payload.ParentEntity.emails[].isPreferredIndicates whether this email is preferred.-
payload.ParentEntity.emails[].okToEmailIndicates whether email communication is allowed.-

Customer, CoBuyer, Lien Holder object

For the table below, ParentEntity can refer to customer, coBuyer, or lienHolder.

Parameter NameDescription
payload.ParentEntity.phoneNumbers[].phoneNumberPhone number for the customer, co-buyer, or lien holder. If sent, it must be exactly 12 characters.
payload.ParentEntity.phoneNumbers[].labelLabel for the phone number.
payload.ParentEntity.phoneNumbers[].isPreferredIndicates whether this phone number is preferred.
payload.ParentEntity.phoneNumbers[].okToTextIndicates whether text communication is allowed.
payload.ParentEntity.phoneNumbers[].okToCallIndicates whether calling is allowed.

Customer, CoBuyer, Lien Holder object

For the table below, ParentEntity can refer to customer, coBuyer, or lienHolder.

Parameter NameDescriptionField Length
payload.ParentEntity.addresses[].line1Address line 1.170
payload.ParentEntity.addresses[].line2Address line 2.170
payload.ParentEntity.addresses[].cityAddress city.-
payload.ParentEntity.addresses[].countyAddress county.-
payload.ParentEntity.addresses[].stateAddress state or region.100
payload.ParentEntity.addresses[].zipAddress postal code.10
payload.ParentEntity.addresses[].countryAddress country.45

payload.deal object

Parameter NameDescription
payload.deal.dealNoDeal number.
payload.deal.dealTypeDeal type from the source DMS.
payload.deal.fiDealTypeF&I deal type.
payload.deal.dealSourceDeal source.
payload.deal.saleTypeSale type.
payload.deal.contractDateContract date.
payload.deal.accountingDateAccounting date.
payload.deal.accountingAccountAccounting account.
payload.deal.salesAccountSales account.
payload.deal.salesDateSales date.
payload.deal.salesManagementDealTypeSales management deal type.
payload.deal.custOrCompanyCodeCustomer or company code from the source system.
payload.deal.hostItemIDHost item identifier.
payload.deal.waqNumberWAQ number.
payload.deal.fiWipStatusCodeF&I work-in-progress status code.
payload.deal.calcMethodCalculation method.
payload.deal.branchBranch value.
payload.deal.leaseTypeLease type.
payload.deal.paymentStylePayment style.
payload.deal.ageAge field from the source DMS.
payload.deal.customerCommentsCustomer comments for the deal.
payload.deal.dealEvents[]List of deal events entries.
payload.deal.contactHistory[]List of contact history entries.

payload.deal.dealEvents object

Parameter NameDescription
payload.deal.dealEvents[].eventCodeDeal event code.
payload.deal.dealEvents[].eventDateDeal event date.

payload.deal.contactHistory Object

Parameter NameDescription
payload.deal.contactHistory[].contactDateContact date for a contact history entry.
payload.deal.contactHistory[].contactReasonContact reason for a contact history entry.

payload.pricing object

Parameter NameDescription
payload.pricing.msrpMSRP value captured at pricing level.
payload.pricing.cashPriceCash price of the vehicle.
payload.pricing.costPriceCost price of the vehicle.
payload.pricing.glVehicleCostGL vehicle cost value.
payload.pricing.salePriceWithWeOwesSale price including we-owe adjustments.
payload.pricing.outTheDoorPriceOut-the-door price.
payload.pricing.adjustedCostOfVehicleAdjusted vehicle cost.
payload.pricing.adjustmentsDealerDefinedDealer-defined adjustment total.
payload.pricing.adjustmentsROPOROPO adjustment total.
payload.pricing.adjustmentsStandardStandard adjustment total.

payload.profit object

Parameter NameDescription
payload.profit.grossProfitGross profit value.
payload.profit.totalGrossTotal gross value.
payload.profit.totalCommissionTotal commission value.
payload.profit.frontEndGrossProfitFront-end gross profit value.
payload.profit.frontGrossFront gross value.
payload.profit.backGrossBack gross value.
payload.profit.commOnSaleDlrDealer commission on sale.
payload.profit.commissionPackCommission pack value.
payload.profit.optionsCommDlrDealer commission on options.
payload.profit.fiIncomeF&I income value.

payload.financing object

Parameter NameDescription
payload.financing.financeAmtFinanced amount.
payload.financing.financeChargeFinance charge.
payload.financing.financeSourceFinance source.
payload.financing.finInstituteCodeFinancing institution code.
payload.financing.aprAPR value.
payload.financing.sellRateAPRSell rate APR.
payload.financing.sellRateAddOnSell rate add-on value.
payload.financing.sellRateLMFSell rate LMF value.
payload.financing.buyRateAPRBuy rate APR.
payload.financing.buyRateAddOnBuy rate add-on value.
payload.financing.buyRateLFMBuy rate LFM value.
payload.financing.buyRateLMFBuy rate LMF value.
payload.financing.bankFeeBank fee.
payload.financing.termFinancing term.
payload.financing.paymentsNumber of payments.
payload.financing.paymentAmtPayment amount.
payload.financing.paymentCodePayment code.
payload.financing.firstPayDateFirst payment date.
payload.financing.lastPayDateLast payment date.
payload.financing.lastPayAmountLast payment amount.
payload.financing.totalOfMonthlyPaymentsTotal of monthly payments.
payload.financing.cashDownCash down amount.
payload.financing.customerCashDownCustomer cash down amount.
payload.financing.dueOnDeliveryAmount due on delivery.
payload.financing.depositAmountDeposit amount.
payload.financing.depositTypeDeposit type.
payload.financing.totalDownTotal down payment.
payload.financing.balloonAmountBalloon amount.
payload.financing.balloonRateBalloon rate.
payload.financing.baseResidualBase residual value.
payload.financing.rebateAmountRebate amount.
payload.financing.incentiveDealerDealer incentive amount.
payload.financing.incentiveProgramIncentive program identifier or name.
payload.financing.surplusCashSurplus cash amount.
payload.financing.securityDepositAmountSecurity deposit amount.

payload.lease object

Parameter NameDescription
payload.lease.leaseEndPercentageRateLease-end percentage rate.
payload.lease.leaseEndValueLease-end value.
payload.lease.leaseMileageAllowanceLease mileage allowance.
payload.lease.leasePaymentLease payment amount.
payload.lease.cashCapReductionCash capitalized cost reduction.
payload.lease.initialCapCostInitial capitalized cost.
payload.lease.adjustedCapCostAdjusted capitalized cost.
payload.lease.addToCapAmountAmount added to cap cost.
payload.lease.amountDueAtStartAmount due at lease start.
payload.lease.totalCapReductionTotal capitalized cost reduction.
payload.lease.totalCashSurplusTotal cash surplus.

payload.taxes object

Parameter NameDescription
payload.taxes.totalTaxTotal tax amount.
payload.taxes.serviceTaxAmountService tax amount.
payload.taxes.usLuxuryExciseTaxAmountUS luxury excise tax amount.
payload.taxes.lstGstAmountLST/GST amount.
payload.taxes.lstGstRateLST/GST rate.
payload.taxes.lstGstRateFlatFlat LST/GST rate.
payload.taxes.texasGAPInsuranceAmountTexas GAP insurance amount.
payload.taxes.texasGAPInsuranceDealerCommissionBaseTexas GAP insurance dealer commission base.
payload.taxes.taxLines[]List of standard tax line items.
payload.taxes.purchaseFlexibleTaxes[]List of flexible purchase tax line items.

payload.taxes.taxLines object

Parameter NameDescription
payload.taxes.taxLines[].taxNameTax line name.
payload.taxes.taxLines[].taxAmountTax line amount.
payload.taxes.taxLines[].taxBaseTax line base amount.
payload.taxes.taxLines[].taxRateTax line rate.

payload.taxes.purchaseFlexibleTaxes object

Parameter NameDescription
payload.taxes.purchaseFlexibleTaxes[].taxNameFlexible tax line name.
payload.taxes.purchaseFlexibleTaxes[].taxAmountFlexible tax line amount.
payload.taxes.purchaseFlexibleTaxes[].taxBaseFlexible tax line base amount.
payload.taxes.purchaseFlexibleTaxes[].taxRateFlexible tax line rate.
payload.taxes.purchaseFlexibleTaxes[].taxMaxFlexible tax line maximum amount.
payload.taxes.purchaseFlexibleTaxes[].taxMaxCodeFlexible tax line maximum code.

payload.fees object

Parameter NameDescription
payload.fees.totalOptionsFeesTotal options fees.
payload.fees.totalFinancedFeeOptionsTotal financed fee options.
payload.fees.totalTaxableFeesTotal taxable fees.
payload.fees.totalInitFeesTotal initial fees.
payload.fees.totalAnnFeesTotal annual fees.
payload.fees.feeOptions[]List of fee option line items.
payload.fees.initialFees[]List of initial fee line items.
payload.fees.annualFees[]List of annual fee line items.
payload.fees.addToCapCostFees[]List of add-to-cap-cost fee line items.

payload.fees.feeOptions object

Parameter NameDescription
payload.fees.feeOptions[].feeNameFee option name.
payload.fees.feeOptions[].feeAmountFee option amount.
payload.fees.feeOptions[].feeCostFee option cost.
payload.fees.feeOptions[].feeProfitTypeFee option profit type.
payload.fees.feeOptions[].dealerCommDealer commission for the fee option.

payload.fees.initialFees object

Parameter NameDescription
payload.fees.initialFees[].feeNameInitial fee name.
payload.fees.initialFees[].feeAmountInitial fee amount.
payload.fees.initialFees[].feeCostAmountInitial fee cost amount.
payload.fees.initialFees[].feeProfitTypeInitial fee profit type.
payload.fees.initialFees[].dealerCommissionBaseDealer commission base for the initial fee.

payload.fees.annualFees object

Parameter NameDescription
payload.fees.annualFees[].feeNameAnnual fee name.
payload.fees.annualFees[].feeAmountAnnual fee amount.
payload.fees.annualFees[].dealerCommBaseDealer commission base for the annual fee.

payload.fees.addToCapCostFees object

Parameter NameDescription
payload.fees.addToCapCostFees[].feeNameAdd-to-cap-cost fee name.
payload.fees.addToCapCostFees[].feeAmountAdd-to-cap-cost fee amount.
payload.fees.addToCapCostFees[].feeCostAmountAdd-to-cap-cost fee cost amount.
payload.fees.addToCapCostFees[].feeProfitTypeAdd-to-cap-cost fee profit type.
payload.fees.addToCapCostFees[].dealerCommBaseDealer commission base for the add-to-cap-cost fee.
payload.fees.addToCapCostFees[].feeFlagSource-system fee flag.

payload.weOwes object

Parameter NameDescription
payload.weOwes.frontWeOwesFront we-owes value.
payload.weOwes.backWeOwesBack we-owes value.
payload.weOwes.frontWeOwesGrossCostFront we-owes gross cost.
payload.weOwes.frontWeOwesGrossSalesFront we-owes gross sales.
payload.weOwes.weOweCostTotalTotal we-owe cost.
payload.weOwes.weOweSaleTotalTotal we-owe sale value.
payload.weOwes.weOweSaleHardTotalTotal hard we-owe sale value.
payload.weOwes.weOweSaleSoftTotalTotal soft we-owe sale value.
payload.weOwes.weOweBackSaleTotalTotal back-sale we-owe value.
payload.weOwes.weOweFrontGrossSalesFront gross sales tied to we-owes.
payload.weOwes.weOweResidualTotalTotal residual value for we-owes.
payload.weOwes.weOweResidualTableTotalResidual table total for we-owes.

payload.insurance object

Parameter NameDescription
payload.insurance.insuranceTypeCodeInsurance type code.
payload.insurance.insuranceCommDlrDealer commission related to insurance.
payload.insurance.totalInsurancePremiumsTotal insurance premiums.
payload.insurance.products[]List of insurance products.
payload.insurance.mbiMechanical breakdown insurance (MBI) details.
payload.insurance.extWarrantyExpMilesLeaseExtended warranty expiration miles for lease.
payload.insurance.extWarrantyTermLeaseExtended warranty term for lease.
payload.insurance.warrantyFeeWarranty fee amount.
payload.insurance.ahAccident and health (AH) insurance details.
payload.insurance.clCredit life (CL) insurance details.
payload.insurance.levelizedLifeLevelized life product details.

payload.insurance.products object

Parameter NameDescription
payload.insurance.products[].insuranceNameInsurance product name.
payload.insurance.products[].insuranceDeductibleInsurance product deductible.
payload.insurance.products[].insuranceLimitInsurance product limit.
payload.insurance.products[].insuranceLimitMilesInsurance product mileage limit.
payload.insurance.products[].insuranceTermInsurance product term.
payload.insurance.products[].insuranceCostInsurance product cost.
payload.insurance.products[].insuranceFeeInsurance product fee.
payload.insurance.products[].insuranceIncomeInsurance product income.

payload.insurance.mbi object

Parameter NameDescription
payload.insurance.mbi.mbiNameMechanical breakdown insurance product name.
payload.insurance.mbi.mbiCarrierMechanical breakdown insurance carrier name.
payload.insurance.mbi.mbiCostMechanical breakdown insurance cost.
payload.insurance.mbi.mbiFeeMechanical breakdown insurance fee.
payload.insurance.mbi.mbiIncomeMechanical breakdown insurance income.
payload.insurance.mbi.mbiDeductibleMechanical breakdown insurance deductible.
payload.insurance.mbi.mbiTermMechanical breakdown insurance term.
payload.insurance.mbi.mbiLimitMechanical breakdown insurance limit.
payload.insurance.mbi.mbiLimitMaxMechanical breakdown insurance maximum limit.
payload.insurance.mbi.mbiPolicyNoMechanical breakdown insurance policy number.
payload.insurance.mbi.mbiEligFlagMechanical breakdown insurance eligibility flag.
payload.insurance.mbi.mbiEligCommentMechanical breakdown insurance eligibility comment.
payload.insurance.mbi.purchaseMBICostPurchase mechanical breakdown insurance cost.
payload.insurance.mbi.purchaseMBISP2CommAmountPurchase mechanical breakdown insurance salesperson 2 commission amount.

payload.insurance.ah object

Parameter NameDescription
payload.insurance.ah.ahCostAccident and health cost.
payload.insurance.ah.ahIncomeAccident and health income.
payload.insurance.ah.ahPremiumAccident and health premium.

payload.insurance.cl object

Parameter NameDescription
payload.insurance.cl.clCostCredit life cost.
payload.insurance.cl.clIncomeCredit life income.
payload.insurance.cl.clPremiumCredit life premium.

payload.insurance.levelizedLife object

Parameter NameDescription
payload.insurance.levelizedLife.amountLevelized life amount.
payload.insurance.levelizedLife.dealerCommLevelized life dealer commission.
payload.insurance.levelizedLife.incomeLevelized life income.

payload.trades object

Parameter NameDescriptionField Length
payload.trades[].tradeVinVIN of the trade vehicle in the deal.17
payload.trades[].tradeVehicleKeySource-system key for the trade vehicle.-
payload.trades[].tradeVehicleUuidmyKaarma or external UUID for the trade vehicle.-
payload.trades[].tradeVehicleMakeTrade vehicle make.100
payload.trades[].tradeVehicleModelTrade vehicle model.45
payload.trades[].tradeVehicleYearTrade vehicle year.4
payload.trades[].tradeVehicleTrimTrade vehicle trim.100
payload.trades[].tradeVehicleEngineTrade vehicle engine description.300
payload.trades[].tradeColorTrade vehicle color.100
payload.trades[].tradeBodyStyleTrade vehicle body style.-
payload.trades[].tradeLicensePlateTrade vehicle license plate.20
payload.trades[].tradeEstimatedMileageEstimated trade vehicle mileage.30
payload.trades[].tradeStockNumberDealer stock number for the trade vehicle.-
payload.trades[].tradeMsrpTrade vehicle MSRP value.-
payload.trades[].tradeGrossTrade vehicle gross value.-
payload.trades[].tradeOverTrade vehicle over-allowance value.-
payload.trades[].tradePayOffTrade vehicle payoff amount.-
payload.trades[].netTradeNet trade value.-

payload.tradeTotals object

Parameter NameDescription
payload.tradeTotals.totalTradeAllowanceTotal trade allowance.
payload.tradeTotals.totalTradesACVTotal ACV across trades.
payload.tradeTotals.totalTradesNetTotal net trade value.
payload.tradeTotals.totalTradesOverTotal trade over-allowance.
payload.tradeTotals.totalTradesPayoffTotal trade payoff amount.

payload.salesTeam object

Parameter NameDescription
payload.salesTeam.salesperson[]List of salesperson identifiers or names.
payload.salesTeam.salesMgrSales manager identifier or name.
payload.salesTeam.closingMgrClosing manager identifier or name.
payload.salesTeam.fiMgr[]List of F&I manager identifiers or names.
payload.salesTeam.billingClerkBilling clerk identifier or name.
payload.salesTeam.deliveryCoordDelivery coordinator identifier or name.
payload.salesTeam.assnSlspersonAssigned salesperson field from the source DMS.
payload.salesTeam.crmSPId[]List of CRM salesperson IDs.
payload.salesTeam.crmSPName[]List of CRM salesperson names.
payload.salesTeam.crmSalesMgrIdCRM sales manager ID.
payload.salesTeam.crmSalesMgrNameCRM sales manager name.
payload.salesTeam.crmFIMgrIdCRM F&I manager ID.
payload.salesTeam.crmFIMgrNameCRM F&I manager name.
payload.salesTeam.crmClosingMgrIdCRM closing manager ID.
payload.salesTeam.crmClosingMgrNameCRM closing manager name.
payload.salesTeam.crmFlagCRM flag value.
payload.salesTeam.crmSaleTypeCRM sale type.

payload.commissions object

Parameter NameDescription
payload.commissions.totalCommissionSP[]List of total commission values for salesperson slots.
payload.commissions.commissionSP[]List of commission values for salesperson slots.
payload.commissions.bonusSP[]List of bonus values for salesperson slots.
payload.commissions.saleCreditSP[]List of sale credit values for salesperson slots.
payload.commissions.crmCommisionSP[]List of CRM commission values for salesperson slots.
payload.commissions.crmCommisionFIMgrCRM commission for the F&I manager.
payload.commissions.crmCommisionSalesMgrCRM commission for the sales manager.
payload.commissions.crmCommisionClosingMgrCRM commission for the closing manager.
payload.commissions.crmCommisionTotalTotal CRM commission amount.
payload.commissions.crmSaleCreditSP[]List of CRM sale credit values for salesperson slots.
payload.commissions.crmSaleCreditFIMgrCRM sale credit for the F&I manager.
payload.commissions.crmSaleCreditSalesMgrCRM sale credit for the sales manager.
payload.commissions.crmSaleCreditClosingMgrCRM sale credit for the closing manager.
payload.commissions.crmSalesCreditTotalTotal CRM sales credit amount.
payload.commissions.crmSpiffSP[]List of CRM spiff values for salesperson slots.
payload.commissions.crmSpiffFIMgrCRM spiff for the F&I manager.
payload.commissions.crmSpiffSalesMgrCRM spiff for the sales manager.
payload.commissions.crmSpiffClosingMgrCRM spiff for the closing manager.
payload.commissions.crmSpiffTotalTotal CRM spiff amount.

payload.pickup object

Parameter NameDescription
payload.pickup.pickupDate[]List of pickup date fields.
payload.pickup.pickupPay[]List of pickup pay fields.