RFC / v0.1Data schemas
Schemas
The object shapes AutomotiveMCP resources exchange. Each is a versioned JSON Schema you can read, validate an object against, and export, one per resource, grouped by the 9 canonical domains defined in §4 Canonical Domains.
For tools, not just readers
Every schema is served at the $id it declares, for example https://automotivemcp.ai/schemas/inventory/vehicle.json with application/schema+json and open CORS, so a validator that follows the identifier gets the document. Each has an example instance alongside it at <entity>.example.json, and the full set is indexed at /schemas/index.json.
Inventory
R01- Vehicleinventory.get_vehicle · inventory.search_vehiclesA single inventory unit at a dealership: a new, used, or manufacturer-certified vehicle with full identity, classification, mechanical spec, condition/history, warranty, pricing, availability, and media. Field lineage draws on the ADF/ADX (Auto-lead Data Format) vehicle block, the Monroney label (window sticker) standard, the NHTSA vPIC VIN-decode catalog, the federal Truth-in-Mileage Act odometer disclosure, and the OpenTrack inventory feed conventions where noted. Consumed by AI agents via inventory.get_vehicle and inventory.search_vehicles.
- Inventory Snapshotinventory.get_snapshotA point-in-time snapshot of a dealer's vehicle inventory feed, returned by inventory.get_snapshot. Captures the feed run metadata, roll-up counts and monetary totals, aging and turn analysis, syndication/merchandising health, and a per-vehicle line summary. Modernizes the traditional flat inventory export (CSV/ADF vehicle listings, IMT/vAuto/HomeNet/DealerSpecialties feeds) into a typed, correlatable JSON envelope so AI agents can reason over stocking, pricing, aging, and merchandising without pulling each Vehicle record individually. Individual vehicles are referenced by id (vehicle_id) rather than embedded in full; fetch the full Vehicle entity from inventory resources when detail is needed.
- Appraisalinventory.get_appraisal · inventory.appraise_tradeA trade-in / vehicle appraisal: a graded condition inspection plus one or more valuations, reconditioning estimates, an outstanding payoff, and a firm trade offer for a single vehicle. Modernizes ADF's <price type="appraisal"> and <condition> blocks into typed JSON, and carries the industry value-guidebook vocabulary (KBB, Black Book, MMR, Galves, NADA/JD Power). Vehicle attributes are captured inline on the appraisal snapshot so the appraised state is preserved even if the underlying Vehicle record later changes.
Leads & CRM
R02- Leadleads.get_lead · leads.create_lead · leads.search_leadsA single sales lead: one shopper's expression of interest in buying, leasing, selling, or trading a vehicle, captured from any channel and tracked through the CRM lifecycle. This entity is the modernized, typed equivalent of an entire ADF (Auto-lead Data Format) XML lead payload, an ADF document describes exactly one lead, so Lead is that document's root object. Field lineage follows ADF throughout: <requestdate> maps to received_at, <prospect status>/@status maps to status + is_resend, <provider> maps to provider, <vehicle interest=...> maps to vehicles_of_interest[].interest, and <timeframe> maps to timeframe. Durable cross-entity relationships (the resolved customer, an assigned salesperson, a scheduled appointment, consent records) are referenced by UUID rather than embedded; the customer's master record lives in the Customer entity, and a lead that converts produces a Deal.
- Customerleads.get_customer · leads.search_customersA full person or business record for a shopper, buyer, or account in the dealership's CRM/DMS. Consolidates the identity, contact points, contactability preferences, consent links, and CRM enrichment (household, tags, segments, lifetime value) that many leads and deals reference. ADF only carried a lightweight <customer><contact> per lead; this entity is the durable, de-duplicated master record those leads resolve to, aligned with common CRM contact objects.
- Activity / Taskleads.get_activity · leads.create_activity · leads.list_activitiesA CRM activity or task, a logged interaction (call, email, text, note, visit, voicemail, chat) or a scheduled to-do (task), recorded against a lead, customer, deal, service order, or appointment. Modernizes the interaction-logging implied by ADF's request/response lifecycle and the follow-up/communication history in the STAR CRM domain into a typed, first-class record that AI agents can read, create, and update.
- Appointmentleads.get_appointment · leads.create_appointmentA scheduled appointment between a dealership and a customer, spanning sales, service, test drive, delivery, appraisal, and finance interactions. Models scheduling, lifecycle status, participants, location, confirmation, reminders, communication consent, recurrence, and cross-entity references to customer, lead, vehicle, and deal. Lineage: aligns with the ADF/ADXML appointment semantics and common DMS/scheduler appointment resources; extends both with explicit confirmation, reminder, no-show/cancellation, and outcome tracking common to modern DMS/CRM/scheduler platforms (CDK, Reynolds & Reynolds, Tekion, DealerSocket, VinSolutions, Xtime, myKaarma).
- Communicationleads.get_communication · leads.list_communications · leads.send_messageA single message or call exchanged between a dealership and a customer/prospect. A Communication is the concrete artifact of an interaction (the email that was sent, the SMS delivered, the phone call recorded), and is distinct from an Activity or Task, which merely LOG that an interaction occurred. Communications capture the full envelope (from/to/cc/bcc/reply_to), content (subject/body/body_html), transport metadata (provider, thread, in_reply_to, delivery timestamps, error codes), channel-specific detail (call recording/transcript/disposition), engagement events (opens/clicks), messaging cost, and the compliance basis for outbound contact (consent_id). Lineage: email/subject/body map to ADF <contact> and CRM email records; direction/channel/status/error_code/segment_count align with common telephony and messaging provider webhooks (e.g. Twilio Message/Call resources, SendGrid Event Webhook, RingCentral) as normalized through common CRM adapters. The TCPA/CAN-SPAM/CASL compliance basis for outbound contact references a Consent record via consent_id.
Deals & Desking
R03- Dealdeals.get_deal · deals.create_quote · deals.desk_dealA full dealership desking record spanning quote through funding and delivery. Models cash, finance, and lease deals with complete pricing (MSRP, discounts, rebates, fees, trade-ins, taxes), lender/lease terms, F&I products, capitalized-cost detail, credit application linkage, compliance flags, and gross. Field lineage follows STAR (Standards for Technology in Automotive Retail) DealXML and RetailDeal payloads, the ADF (Auto-lead Data Format) lead structures, the federal Truth in Lending Act (Reg Z) and Consumer Leasing Act (Reg M) disclosure boxes, and 700Credit/RouteOne/Dealertrack credit-bureau conventions where relevant. Cross-entity relationships (customer, vehicle, salesperson, appraisal) are referenced by UUID rather than embedded.
- Incentivedeals.list_incentives · deals.get_incentiveAn OEM, dealer, lender, or regional incentive, a rebate, subvented APR, lease-cash, or bonus-cash offer that can be applied to a Deal to reduce price, buy down a rate, or improve lease economics. Incentives are catalog records: they are matched against a vehicle and customer at desking time via their eligibility and applies_to constraints, then referenced by id from a Deal's incentive lines. Money and rate structures follow ADF's <finance> block conventions (amount/percent/balance types), and program_code mirrors the OEM program identifiers surfaced through OEM incentive feeds.
Service
R04- Service Orderservice.get_order · service.create_order · service.list_ordersA dealership repair order (RO), the authoritative record of a service visit, from write-up through invoice and payment. Captures the vehicle, advisor, mileage, and a set of operation lines (labor, parts, sublet, fee) each with complaint/cause/correction (the 3 C's), pay type, and optional warranty claim data. Rolls up parts/labor/sublet/fees/discount/tax into totals, records payments, and carries declined recommendations for follow-up marketing. Modernizes DMS service-RO structures and the ADF <service> lineage into a typed JSON entity; links customer, vehicle, appointment, advisor, technicians, parts, and warranty claim by id rather than embedding them. May carry PII on the payer/customer via linked records and denormalized contact fields, handle under the spec's Auth & Security profile.
- Recallservice.get_recall · service.list_recallsA manufacturer safety recall (typically an NHTSA campaign, plus its OEM-internal counterpart) affecting a specific vehicle in the dealer's operational context. Captures the campaign identity (nhtsa_campaign_number / oem_recall_number), the affected vehicle and its decoded make/model/year/VIN, the regulatory narrative (component, summary, consequence, remedy) as published by the manufacturer under 49 CFR Part 573, the risk classification, parts and remedy availability, owner-notification milestones, the stop-sale / do-not-drive posture, and the local completion workflow (scheduled/completed timestamps and the service order that performed the fix) including the warranty labor operation claimed. One Recall record represents one campaign as it applies to one vehicle; a vehicle with three open campaigns yields three Recall records. Lineage: campaign narrative and milestone fields map to NHTSA's Recalls API (api.nhtsa.gov recallsByVehicle / SafercarRecallsByVehicle endpoints) and OEM warranty/recall feeds (e.g. Ford OASIS, GM GWM/VIS, Toyota TIS); the vehicle linkage and remedy workflow extend ADF service intents into a typed record a DMS or CRM can act on.
- Warranty Claimservice.get_warranty_claim · service.submit_warranty_claimA warranty or service-contract claim submitted by a dealer's service department against an OEM factory warranty, a powertrain warranty, an extended service contract (ESC/VSC) administrator, a goodwill authorization, a safety recall, or a technical service bulletin (TSB). Captures the failed operation, the repair performed (labor operations, parts, and hours), the complaint/cause/correction narrative, the amounts requested and approved, chargeback/rejection detail, and the full submitted/decisioned/paid lifecycle. Sits downstream of a Service Order (repair order): the RO documents the physical work, the Warranty Claim is the reimbursement request filed against a payer. Extends ADF and STAR warranty-claim messaging into a typed, line-itemized JSON record so AI agents can read claim status and submit new claims through a dealer's DMS or a third-party warranty-administration platform.
Parts
R05- Partparts.get_part · parts.search_parts · parts.check_availabilityA single parts-catalog / inventory item in a dealer parts department, modeled richly for DMS, e-commerce, and AI-agent consumption. Modernizes ADF's parts-order line items into a typed, catalog-aware JSON entity that carries manufacturer identity, supersession chains, multi-location on-hand inventory, tiered pricing (list / cost / core / selling / MAP), unit-of-measure and packaging, hazmat/regulatory metadata, and year-range fitment. Referenced by service and deal entities via part_id.
- Parts Orderparts.get_order · parts.create_order · parts.list_ordersA parts procurement order raised by a dealer parts department against a vendor or manufacturer. Captures the full lifecycle of stock replenishment, special orders, emergency orders, and returns, including per-line quantities ordered/received/backordered/shipped/canceled, dealer-cost, list-price and core-charge money, rolled-up totals, ship-to / bill-to addresses, freight and payment terms, return/RMA handling, and shipment tracking. Links to the Vendor, Dealer, and (when the order backs a repair order or a retail counter sale) the Service Order and Customer. Modernizes DMS parts-order messaging into a typed JSON entity that a DMS or parts catalog can implement against for parts.get_order, parts.create_order, and parts.list_orders.
F&I
R06- Credit Applicationfni.get_credit_application · fni.submit_credit_applicationAn F&I (Finance & Insurance) credit application submitted for a vehicle deal at a dealership. Captures the applicant (and optional co-applicant) identity, residence and employment history, requested financing terms, credit bureau pull results, per-lender decisions, and the contracted/booked terms. Lineage: derived from ADF (Auto-lead Data Format) credit sub-elements, the RouteOne and Dealertrack credit application specifications, the STAR (Standards for Technology in Automotive Retail) Credit BOD, 700Credit / CBC bureau responses, and StoneEagle / MenuVantage F&I data models. SECURITY: This entity carries Personally Identifiable Information (PII) and non-public personal financial information governed by GLBA, FCRA, and ECOA (Reg B). Every field marked "x-pii": true MUST be transmitted and stored under the AutomotiveMCP.AI Auth & Security profile (mutual TLS, field-level encryption at rest, scoped OAuth, audit logging). Full Social Security Numbers, full driver-license numbers, and full account numbers are NEVER modeled, only truncated last-4 fragments are permitted.
- F&I Productfni.get_product · fni.list_productsA finance-and-insurance (F&I) product as either a menu item presented in the F&I office or a sold instance attached to a deal, vehicle service contracts (VSC), GAP, tire-and-wheel, prepaid maintenance, credit life/disability, and similar aftermarket coverages. Models the product catalog entry, its coverage terms, three-tier pricing (dealer cost, retail, sold), the reserve/commission economics F&I managers desk against, regulatory disclosure metadata, and the full sold-and-canceled lifecycle including chargebacks. Complements the Deal and Credit Application entities: an F&I Product references the deal, customer, vehicle, and lender by id rather than embedding them. Product structure and cancellation semantics mirror how DMS F&I modules (Reynolds, CDK, Dealertrack) and menu-selling platforms (MenuMetric, StoneEagle, Darwin) export aftermarket line items; there is no first-class ADF <finance> element for aftermarket products, so this schema standardizes the shape the DMS carries alongside the ADF deal.
- Lenderfni.get_lender · fni.list_lendersA finance source (lender) the dealer submits F&I deals to for approval and funding, captive finance arms, banks, credit unions, subprime/special-finance houses, buy-here-pay-here portfolios, and lease sources. Models the lender's identity, dealer relationship, contact of record, credit programs / rate tiers, dealer reserve (participation) structure, funding method, and the fees/holdbacks/state constraints that govern deal economics. Lineage: ADF carried lender data only as a free-text finance-source string on the credit request; this entity promotes it to a first-class typed record so agents can shop a deal across sources, honor program tiers, and reason about reserve/rate economics. Program rate sheets and buy rates are commercially sensitive and are marked x-pii for handling parity; they are business-confidential rather than consumer PII.
Marketing & Analytics
R07- Campaignsignals.get_campaign · signals.list_campaignsA marketing campaign in the Marketing & Analytics (signals) domain. Models the outbound program a dealership or agency runs across channels (email, SMS, direct mail, paid/organic media, events, equity mining) together with its audience, schedule, budget, offers, creatives, UTM attribution, consent/compliance posture, attribution model, pacing, and rolled-up performance metrics. Complements ADF's lead <provider>/<vendor>/<source> attribution by naming the campaign that sourced a lead: a Lead's campaign_id references this entity, and the UTM block mirrors the utm_* parameters that most CRMs stamp onto web-sourced leads.
- Audiencesignals.get_audience · signals.list_audiences · signals.list_audience_membersA marketing audience or segment in the Marketing & Analytics (signals) domain (spec §4 R07 'Audiences'). An Audience is a named, reusable group of people or accounts assembled from a CDP, DMS, CRM, website behavior, manual upload, or a third-party source, and activated against advertising and messaging platforms. Static audiences are fixed membership snapshots; dynamic audiences are rule-driven and recomputed on refresh; lookalike audiences are modeled from a seed; suppression audiences exclude members from targeting. Audiences complement the Campaign entity (which references an audience for delivery) and provide the population that ADF lead attribution ultimately draws from. Member records themselves are enumerated separately via signals.list_audience_members and are not embedded here.
- Eventsignals.list_events · signals.get_eventA single signal in the read-only engagement/sale/service stream of the Marketing & Analytics (signals) domain (spec §4 R07 'Events'). Each Event is an immutable, append-only record of one thing that happened for one customer at one dealer, a page view, an ad click, a conversion, an inbound lead, an outbound email/SMS touch, or a fixed-ops (service) milestone. Events unify web analytics (page_view, input_tracking, ad_click, conversion), CRM/marketing engagement (lead, enrichment, email_*, sms_*), retail sale (sale), and service-lane activity (service_lead, service_appointment, service_ro, appointment) into one time-ordered feed. This domain is READ-ONLY: producers emit events, consumers (AI agents) subscribe via signals.list_events and signals.get_event, but no tool mutates an Event after it is written. ADF lineage: an inbound 'lead' event typically corresponds to the arrival of an ADF <adf><prospect> payload (see leads/lead.json), and 'sale'/'service_ro' events align with DMS deal-jacket and repair-order milestones.
Consent & Compliance
R08- Consent Recordconsent.get_consent · consent.check_consent · consent.record_consentA single customer consent decision for one communication channel and scope (e.g. SMS marketing), capturing the grant/revoke status plus the evidence and verbatim disclosure needed to prove it under TCPA/CTIA, CAN-SPAM, GDPR/ePrivacy, CCPA/CPRA, and CASL. This is data ADF never modeled; it is the compliance showpiece of the standard and maps to spec domain R08 Consent & Compliance. Resources: consent.get_consent, consent.check_consent, consent.record_consent.
- Consent Receiptconsent.get_receipt · consent.verify_receipt · consent.report_revocationThe payload of a consent receipt (spec §9.3): a signed, self-contained assertion about one consent record, issued by the capturing party to one named relying party. The receipt itself is a JWS in compact serialization (RFC 7515), signed with an asymmetric algorithm (ES256 MUST be supported, 'none' MUST NOT be accepted); this schema describes the claims inside it. Claims follow §9.3.1, which remains the normative definition. Timestamps are JWT NumericDate values (seconds since the Unix epoch), not RFC 3339 strings, because the payload is a JWS claim set. A receipt is a statement about consent, not a grant of access or an authentication credential. Resources: consent.get_receipt, consent.verify_receipt, consent.report_revocation.
Core & Reference
R09- Dealercore.get_dealer · core.list_dealersA single dealership rooftop, the selling/servicing organization referenced as dealer_id across the standard by leads, deals, inventory snapshots, service orders, parts, and campaigns. Models the OEM franchise relationship (dealer codes per make), the physical and mailing location, contact channels, department-level hours and contacts, licensing/tax identity, and lifecycle. Where the legacy ADF world carried this context implicitly inside a <vendor> block on each lead, this entity makes the rooftop a first-class, addressable record.
- Employeecore.get_employee · core.list_employeesA staff member or system user at a dealership, a salesperson, service advisor, technician, F&I manager, BDC agent, or manager. The Employee is the referent for the many actor pointers scattered across the standard: advisor_id on a Service Order, technician_id on a repair line, salesperson_id and fi_manager_id on a Deal, owner_id / assigned_to_id on a Lead, and assigned_to_id on an Activity Task all resolve to an Employee id. Employees also carry the crm_user_id and dms_user_id needed to reconcile the same person across the CRM and DMS. ADF lineage: the <salesperson>-style actor blocks ADF never formally typed are normalized here into a single first-class entity so agents can attribute and route work to a real, correlatable person.
- Vendorcore.get_vendor · core.list_vendorsAn external vendor or supplier that a dealership transacts with, parts suppliers, sublet repair shops, marketing agencies, service providers, lenders, OEM entities, insurance carriers, transport carriers, and other counterparties. Vendors are the payee/supplier side of dealership accounts payable and procurement, complementing customer (accounts receivable) records. There is no ADF (Auto-lead Data Format) analog for vendors, ADF models lead/customer flows, so this entity draws instead on DMS/ERP accounts-payable master data and common supplier-master conventions to expose supplier master records to AI agents in a typed, portable form.
- Documentcore.get_document · core.list_documentsA document or artifact produced or consumed during a dealership transaction, a purchase agreement, retail installment contract, lease agreement, credit application printout, consent form, signed PDF, title, or e-signature envelope. Captures the file's identity, lifecycle status, what business object it belongs to, retrieval location, integrity, retention posture, and any signatures collected against it. ADF never modeled documents; this fills that gap and maps to the spec's core Document domain. SENSITIVE: a document may embody PII (SSN fragments, DOB, driver's license, financial terms) inside the referenced file; the is_pii / pii_categories flags and signature ip_address / signer_email / signer_phone / signer_name carry x-pii and MUST be handled under the spec's Auth & Security profile.