Skip to main content

Modal Auto-lead Data Format (ADF) Version 2.0

Michael Falgien
  • Updated

Table of Contents

  1. Overview
  2. CRM quick setup
  3. Modal products
  4. Summary of <provider> field values
  5. Available values In the <service> field
  6. Modal transaction types
  7. Modal Checkout steps
  8. Corresponding <id> and "source" format
  9. List of all possible values in the <id> and "source" fields
  10. Shift Digital partner integration

 

Overview

  • Lead information is sent to the dealership CRM email address on file with Modal using the Auto-lead Data Format (ADF) XML. 
  • Modal leads can be mapped into the CRM for followup and reporting based on the <provider> section of the ADF lead.
  • Dealers and their CRM team should reference the values listed in this article to reconfigure their CRM to accommodate the changes.
  • Modal currently supports two formats with Version 1.0 becoming deprecated in August 2020,  This document summarizes Version 2.0, which is now the default format.
  • If your lead email subject or provider contain "Drive Motors" then you are using Modal's ADF lead version 1.0; Please contact your CSM or support@modalup.com to upgrade to Modal ADF leads version 2.0
  • Version 2.0's email subject line will read "New {transaction type} from Modal" where transaction type is one of the values listed below.

 

CRM quick setup

The dealership CRM can be configured to use the Modal ADF content to trigger the appropriate response flows. A Modal Order represents a customer completing the Modal Checkout process, and they should receive different communication than a customer who has not yet completed the process, in accordance with Modal's training guidelines and the dealership's established practices.

With source as the primary lead identification field

<provider>
    <name part="full">Modal Checkout - save order - review</name>
    <email>sales@drivemotors.com</email>
    <phone type="voice">8662006766</phone>
    <service>Modal Checkout - lead button</service>
    <id source="Modal" sequence="172743">3220</id>
</provider>

OR, with name as the primary lead identification field

<provider>
    <name part="full">Modal</name>
    <email>sales@drivemotors.com</email>
    <phone type="voice">8662006766</phone>
    <service>Modal Checkout - lead button</service>
    <id source="Modal Checkout - save order - review" sequence="172743">3220</id>
</provider>
  1. Let Modal know which CRM you work with and whether your CRM parsing is based primarily on the ADF "source" or "name" field.
  2. Modal will enable the proper configuration for your dealer so the lead type is declared either in the ADF "source" or "name" field.
  3. Order: If the lead type contains "- approved order", "- order", or "- non credit order", the customer finished the Modal Checkout process with the intent to buy or lease a vehicle.
  4. Partial Order: If the lead type contains "- save order", "- abandon", or "- message", the customer has not finished the Modal Checkout process.
  5. Trade: If the lead type contains "tradein appraisal", the customer estimated their vehicle's value using Modal's Trade module.

 

Modal products

The products listed below are the primary Modal systems that can trigger a ADF output to a dealer's CRM.  This table can be referenced to understand which Modal product was engaged during the buyer's session.  

Product name

Description
Checkout Modal's flagship product places a 'Buy' button on vehicles on the dealer's website, facilitates the retail transaction where the user submits their trade information, selects upgrades, receives payment estimates, and collects credit approvals.
Trade Places a trade valuation banner on the dealer's website such as "What's my car worth?" where the user gets an estimated trade value for their vehicle.
Dashboard Modal's admin page for dealers to see all of their Customers, Orders, Leads, and Trades. Dealers can also re-engage their customers with custom deals and send messages.
Shop Virtual showroom where the user can browse the dealer's inventory in a clean, convenient interface, from which the user can engage in Checkout and Trade sessions, and the dealer staff can compose custom deals.

 

Summary of <provider> field values

Lead information will be included within the <provider></provider> XML tags.  This section will have five fields.  The table below summarizes the values Modal will send for each field.

<provider>
    <name part="full">Modal</name>
    <email>sales@drivemotors.com</email>
    <phone type="voice">8662006766</phone>
    <service>Modal Checkout - lead button</service>
    <id source="Modal Checkout - save order - review" sequence="172743">3220</id>
</provider>

Field

Description
<provider><name>

The name describes the Modal product used, the Modal transaction type, the last completed step of the Checkout session, and the Modal lead ID. Or, if your CRM uses source as the primary lead type differentiatior, the name will simply be "Modal".

source="{product name} - {transaction type} - {from step}"
<provider><email> Defaults to "sales@drivemotors.com"
<provider><phone> Defaults to "8662006766"
<provider><service>

Describes the Modal product used and which Modal CTA was used to start the session.

<service>{product name} - {CTA name}</service>
<provider><id> 

The source describes the Modal product used, the Modal transaction type, the last completed step of the Checkout session, and the Modal lead ID. Or, if your CRM uses name as the primary lead type differentiatior, the source will simply be "Modal".

source="{product name} - {transaction type} - {from step}"

sequence is the lead ID in Modal's system

<id> value is a 4 digit code that maps 1:1 with the human-readable source

 

Available values in the <service> field 

The <service> field will only be populated when transaction type is save order, abandon, or message.

<service>

Description

Modal Checkout - buy button

 Website button such as 'Buy online' which starts a Checkout session.

Modal Checkout - lead button

 Website button such as 'Buy online' which collects the user's contact information, then starts a Checkout session.

Modal Checkout - savings button

 Website button such as 'See my savings' which collects the user's contact information, displays the vehicle price, then starts a Checkout session.

Modal Checkout - payment button

 Website button such as 'Build payment' which opens a payment estimate calculator at the beginning of a Checkout session.

Modal Checkout - tradein button

 Website button such as 'Value trade' which opens the trade estimation step at the beginning of a Checkout session.

Modal Dashboard - deal text button

 Dealer sent a text message SMS to Customer for their custom Deal

Modal Dashboard - deal email button

 Dealer sent an email to Customer for their custom Deal

Modal Dashboard - deal link button

 Dealer copied a custom Deal link then sent it to the Customer

Modal Shop - tradein button

 Each page contains a menu with a "Trade" button to launch a Trade session. 

Modal Shop - buy button

 Each vehicle displays a "Buy" button to launch a Checkout session.

Modal Shop - saveorder button

 Each vehicle displays a "Share" button for the user to send a link to start a Checkout session later.

Modal Trade - tradein banner

 Trade CTA on the dealer website, such as "What's my car worth?"

 

Modal transaction types

Transaction Type

Modal Product(s)

Description

approved order

 Checkout, Shop Customer submitted a credit application, completed the Checkout flow, and selected an approved payment from a lender

order

 Checkout, Shop Customer submitted a credit application and completed the Checkout flow without an approved payment from a lender

non credit order

 Checkout, Shop Customer completed the Checkout flow and chose to skip submitting a credit application

save order

 Checkout, Shop User sent themselves a link to continue their Checkout session later
abandon Checkout, Shop User entered contact info and left the Checkout session without completing their order
message Checkout, Shop User sent the dealer a message from within the Checkout flow

tradein appraisal

 Trade, Shop User entered their trade information to receive an estimated value

deal shared to customer

 Dashboard Dealer employee created a custom Deal, then sent a link to the Customer

 

Modal Checkout steps

A Modal Checkout session is a series of steps that varies based on the dealer settings and the CTA used to start the session.  The last completed step will sometimes but not always be included as part of the source.  The transaction types approved order, order, non credit order, and tradein appraisal are considered complete sessions, and do not include the last step completed.

The example below demonstrates the ordering of steps for the buy button, lead button, or savings button:

checkout start -> trade -> payment -> upgrades -> delivery -> billing info -> approval info -> cobuyer billing info (optional) -> cobuyer approval info (optional) -> credit decisions -> review

The example below demonstrates the ordering of steps for the tradein button:

trade -> payment -> upgrades -> delivery -> billing info -> approval info -> cobuyer billing info (optional) -> cobuyer approval info (optional) -> credit decisions -> review

The example below demonstrates the ordering of steps for the payment button:

payment modal -> checkout start -> trade -> payment -> upgrades -> delivery -> billing info -> approval info -> cobuyer billing info (optional) -> cobuyer approval info (optional) -> credit decisions -> review

 

Corresponding <id> and "source"/"name" format

The ADF <provider><id> value is a 4 digit code that maps 1:1 with the human-readable source or name value, and describes the Modal product used, the Modal transaction type, and the last completed step of the Checkout session.

Proprietary Id value format

{1-digit Product Name Code} {1-digit Transaction Type Code} {2-digit Last Step Code}

Product Name 1st digit of <id>
Modal Checkout 1
Modal Dashboard 2
Modal Shop 3
Modal Trade 4

{1-digit Product Name Code} {1-digit Transaction Type Code} {2-digit Last Step Code}

Transaction Type 2nd digit of <id>

approved order

order

non credit order

tradein appraisal

 0
abandon 1
save order 2
message 3
deal shared to customer 5
test drive 6

{1-digit Product Name Code} {1-digit Transaction Type Code} {2-digit Last Step Code}

Modal Checkout and Modal Shop: {last step completed} 3rd and 4th digits of <id>
null 00
payment modal 07
checkout start 08
upgrades 10
trade 20
delivery 30
payment 40
billing info 50
cobuyer billing info 55
approval info 60
cobuyer approval info 65
credit decisions 70
review 80
non credit order 90
order 92
approved order 95
modal trade 25

 

List of all possible values in the <id> and "source"/"name" fields

This list summarizes the set of values that Modal can send.  CRM administrators can use this list to configure the correct follow up behavior within a CRM.

*Bold items below represent leads where the user completed the Checkout or Trade session with the intent to buy, lease, or trade a vehicle. Other items represent abandons, messages, saved orders where the user did not yet complete their session.

** If your CRM uses name as the primary lead parsing differentiation field, you will find the lead types in the name field, and source will simply be "Modal"

<id source="Modal Checkout - approved order">1095</id>
<id source="Modal Checkout - order">1092</id>
<id source="Modal Checkout - non credit order">1090</id>
<id source="Modal Trade - tradein appraisal">4025</id>
<id source="Modal Dashboard - deal shared to customer">2500</id>
<id source="Modal Checkout - abandon">1100</id>
<id source="Modal Checkout - abandon - payment modal">1107</id>
<id source="Modal Checkout - abandon - upgrades">1110</id>
<id source="Modal Checkout - abandon - trade">1120</id>
<id source="Modal Checkout - abandon - delivery">1130</id>
<id source="Modal Checkout - abandon - payment">1140</id>
<id source="Modal Checkout - abandon - billing info">1150</id>
<id source="Modal Checkout - abandon - cobuyer billing info">1155</id>
<id source="Modal Checkout - abandon - approval info">1160</id>
<id source="Modal Checkout - abandon - cobuyer approval info">1165</id>
<id source="Modal Checkout - abandon - credit decisions">1170</id>
<id source="Modal Checkout - abandon - review">1180</id>
<id source="Modal Checkout - save order">1200</id>
<id source="Modal Checkout - save order - upgrades">1210</id>
<id source="Modal Checkout - save order - trade">1220</id>
<id source="Modal Checkout - save order - delivery">1230</id>
<id source="Modal Checkout - save order - payment">1240</id>
<id source="Modal Checkout - save order - billing info">1250</id>
<id source="Modal Checkout - save order - cobuyer billing info">1255</id>
<id source="Modal Checkout - save order - approval info">1260</id>
<id source="Modal Checkout - save order - cobuyer approval info">1265</id>
<id source="Modal Checkout - save order - credit decisions">1270</id>
<id source="Modal Checkout - save order - review">1280</id>
<id source="Modal Checkout - message">1300</id>
<id source="Modal Checkout - message - upgrades">1310</id>
<id source="Modal Checkout - message - trade">1320</id>
<id source="Modal Checkout - message - delivery">1330</id>
<id source="Modal Checkout - message - payment">1340</id>
<id source="Modal Checkout - message - billing info">1350</id>
<id source="Modal Checkout - message - cobuyer billing info">1355</id>
<id source="Modal Checkout - message - approval info">1360</id>
<id source="Modal Checkout - message - cobuyer approval info">1365</id>
<id source="Modal Checkout - message - credit decisions">1370</id>
<id source="Modal Checkout - message - review">1380</id>
<id source="Modal Checkout - test drive">1600</id>
<id source="Modal Checkout - test drive - lead collect">1603</id>
<id source="Modal Checkout - test drive - price reveal">1605</id>
<id source="Modal Checkout - test drive - payment modal">1607</id>
<id source="Modal Checkout - test drive - checkout start">1608</id>
<id source="Modal Checkout - test drive - upgrades">1610</id>
<id source="Modal Checkout - test drive - trade">1620</id>
<id source="Modal Checkout - test drive - delivery">1630</id>
<id source="Modal Checkout - test drive - payment">1640</id>
<id source="Modal Checkout - test drive - billing info">1650</id>
<id source="Modal Checkout - test drive - cobuyer billing info">1655</id>
<id source="Modal Checkout - test drive - approval info">1660</id>
<id source="Modal Checkout - test drive - cobuyer approval info">1665</id>
<id source="Modal Checkout - test drive - credit decisions">1670</id>
<id source="Modal Checkout - test drive - review">1680</id>
<id source="Modal Dashboard - document uploaded">2098</id>
<id source="Modal Dashboard - appointment set">2097</id>
<id source="Modal Dashboard - approved order">2095</id>
<id source="Modal Dashboard - order">2092</id>
<id source="Modal Dashboard - non credit order">2090</id>
<id source="Modal Dashboard - abandon">2100</id>
<id source="Modal Dashboard - abandon - lead collect">2103</id>
<id source="Modal Dashboard - abandon - price reveal">2105</id>
<id source="Modal Dashboard - abandon - payment modal">2107</id>
<id source="Modal Dashboard - abandon - checkout start">2108</id>
<id source="Modal Dashboard - abandon - upgrades">2110</id>
<id source="Modal Dashboard - abandon - trade">2120</id>
<id source="Modal Dashboard - abandon - delivery">2130</id>
<id source="Modal Dashboard - abandon - payment">2140</id>
<id source="Modal Dashboard - abandon - billing info">2150</id>
<id source="Modal Dashboard - abandon - cobuyer billing info">2155</id>
<id source="Modal Dashboard - abandon - approval info">2160</id>
<id source="Modal Dashboard - abandon - cobuyer approval info">2165</id>
<id source="Modal Dashboard - abandon - credit decisions">2170</id>
<id source="Modal Dashboard - abandon - review">2180</id>
<id source="Modal Dashboard - save order">2200</id>
<id source="Modal Dashboard - save order - checkout start">2208</id>
<id source="Modal Dashboard - save order - payment modal">2207</id>
<id source="Modal Dashboard - save order - upgrades">2210</id>
<id source="Modal Dashboard - save order - trade">2220</id>
<id source="Modal Dashboard - save order - delivery">2230</id>
<id source="Modal Dashboard - save order - payment">2240</id>
<id source="Modal Dashboard - save order - billing info">2250</id>
<id source="Modal Dashboard - save order - cobuyer billing info">2255</id>
<id source="Modal Dashboard - save order - approval info">2260</id>
<id source="Modal Dashboard - save order - cobuyer approval info">2265</id>
<id source="Modal Dashboard - save order - credit decisions">2270</id>
<id source="Modal Dashboard - save order - review">2280</id>
<id source="Modal Dashboard - message">2300</id>
<id source="Modal Dashboard - message - checkout start">2308</id>
<id source="Modal Dashboard - message - upgrades">2310</id>
<id source="Modal Dashboard - message - trade">2320</id>
<id source="Modal Dashboard - message - delivery">2330</id>
<id source="Modal Dashboard - message - payment">2340</id>
<id source="Modal Dashboard - message - billing info">2350</id>
<id source="Modal Dashboard - message - cobuyer billing info">2355</id>
<id source="Modal Dashboard - message - approval info">2360</id>
<id source="Modal Dashboard - message - cobuyer approval info">2365</id>
<id source="Modal Dashboard - message - credit decisions">2370</id>
<id source="Modal Dashboard - message - review">2380</id>
<id source="Modal Dashboard - assign employee">2400</id>
<id source="Modal Dashboard - deal shared to customer">2500</id>
<id source="Modal Shop - document uploaded">3098</id>
<id source="Modal Shop - appointment set">3097</id>
<id source="Modal Shop - tradein appraisal">3025</id>
<id source="Modal Shop - approved order">3095</id>
<id source="Modal Shop - order">3092</id>
<id source="Modal Shop - non credit order">3090</id>
<id source="Modal Shop - abandon">3100</id>
<id source="Modal Shop - abandon - payment modal">3107</id>
<id source="Modal Shop - abandon - upgrades">3110</id>
<id source="Modal Shop - abandon - trade">3120</id>
<id source="Modal Shop - abandon - delivery">3130</id>
<id source="Modal Shop - abandon - payment">3140</id>
<id source="Modal Shop - abandon - billing info">3150</id>
<id source="Modal Shop - abandon - cobuyer billing info">3155</id>
<id source="Modal Shop - abandon - approval info">3160</id>
<id source="Modal Shop - abandon - cobuyer approval info">3165</id>
<id source="Modal Shop - abandon - credit decisions">3170</id>
<id source="Modal Shop - abandon - review">3180</id>
<id source="Modal Shop - save order">3200</id>
<id source="Modal Shop - save order - upgrades">3210</id>
<id source="Modal Shop - save order - trade">3220</id>
<id source="Modal Shop - save order - delivery">3230</id>
<id source="Modal Shop - save order - payment">3240</id>
<id source="Modal Shop - save order - billing info">3250</id>
<id source="Modal Shop - save order - cobuyer billing info">3255</id>
<id source="Modal Shop - save order - approval info">3260</id>
<id source="Modal Shop - save order - cobuyer approval info">3265</id>
<id source="Modal Shop - save order - credit decisions">3270</id>
<id source="Modal Shop - save order - review">3280</id>
<id source="Modal Shop - message">3300</id>
<id source="Modal Shop - message - upgrades">3310</id>
<id source="Modal Shop - message - trade">3320</id>
<id source="Modal Shop - message - delivery">3330</id>
<id source="Modal Shop - message - payment">3340</id>
<id source="Modal Shop - message - billing info">3350</id>
<id source="Modal Shop - message - cobuyer billing info">3355</id>
<id source="Modal Shop - message - approval info">3360</id>
<id source="Modal Shop - message - cobuyer approval info">3365</id>
<id source="Modal Shop - message - credit decisions">3370</id>
<id source="Modal Shop - message - review">3380

 

Shift Digital partner integration

 

 

Documentation Changelog

  • 1.0 / July 1, 2020: Initial draft release.
  • 1.1 / July 16, 2020: Reformatted text and tables.
  • 1.2 / July 17, 2020: General language updates and improvements.  Updated document flow.
  • 1.3 / July 31, 2020: Adding Shift Digital section.
  • 1.4 / Dec 31, 2020: Adjust default checkout step ordering and add 'checkout start' step
  • 1.5 / Feb 12, 2021: Add 'Create a deal' lead info
  • 1.6 / May 6, 2021: Add 'Test Drive' lead info
  • 1.7 / September 1, 2021: Adding example adf XML file

Related articles

Comments

0 comments

Please sign in to leave a comment.