canonical: https://jentic.com/apis/dealerai.com/dealerai

# DealerAI API

DealerAI is an AI assistant platform for automotive dealerships, exposing a focused v1 API that covers contact ingestion, conversational engagement, and vehicle inventory feeds. The 8 endpoints split between an AI lead-management surface (`/ailm/contact`, `/ailm/engage`), a conversation log reader, and inventory operations for new and used vehicles, including a VIN-keyed lookup. Authentication is HTTP Basic, and the API is designed to be called from dealership management systems pushing inventory and lead events into DealerAI's chat workflows.

## For AI agents

Push dealership leads and inventory into DealerAI, trigger AI engagement on a contact, and read back the resulting conversations or look up a vehicle by VIN.

## Scope

Does not handle finance applications, service scheduling, F&I document workflows, or deal-jacket management - use for DealerAI lead engagement and inventory feeds only.

## Capabilities

- Create or update a dealership contact without sending a message via `/ailm/contact`
- Queue an AI-driven engagement against a contact through `/ailm/engage`
- Retrieve conversation transcripts produced by the DealerAI assistant
- Upload new vehicle inventory and refresh used vehicle inventory feeds
- Look up a single vehicle by VIN to confirm it is present in the dealership feed

## Use cases

### DMS-to-DealerAI lead sync

Dealerships running a CRM or DMS need leads to land in DealerAI so the AI assistant can follow up. POST `/ailm/contact` creates or updates the contact silently, while POST `/ailm/engage` takes the same identifier and queues an outbound engagement. Splitting the two operations lets a workflow seed contacts in bulk overnight and engage selectively the next morning.

Example prompt: POST `/ailm/contact` with the lead payload, then POST `/ailm/engage` with the same contact identifier to start the AI follow-up.

### Inventory feed maintenance

DealerAI's responses depend on accurate vehicle data. POST `/inventory/new` and POST `/inventory/used` push fresh feeds, while the corresponding GETs let an agent reconcile what DealerAI currently holds against the source of truth. `/inventory/vehicle/{vin}` is the single-VIN lookup used to confirm a specific car is live before pointing a customer at it.

Example prompt: POST `/inventory/used` with the day's used-car feed, then GET `/inventory/vehicle/{vin}` for any VIN that should be highlighted to a customer.

### Conversation review and quality monitoring

Sales managers want visibility into how the AI assistant is handling leads. GET /conversations returns the recent conversation log so a workflow can pull transcripts, score them, and surface low-quality or stalled threads to a human BDC rep. This is also useful for building an offline analytics store of dealership AI interactions.

Example prompt: GET /conversations with a date filter and forward any thread without a human reply in 24 hours to a sales manager.

### AI agent orchestrating dealership outreach via Jentic

An agent embedded in a dealership workflow can use Jentic to discover DealerAI's contact and engage endpoints, ingest a lead from a website form, and trigger AI follow-up - all without exposing the HTTP Basic credentials. The agent can then poll /conversations to confirm the lead was engaged and escalate if not.

Example prompt: Search Jentic for 'engage a DealerAI contact', execute `/ailm/engage` with the new lead, then GET /conversations to confirm the engagement started.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/ailm/contact` | Create or update a dealership contact |
| POST | `/ailm/engage` | Queue an AI engagement for a contact |
| GET | `/conversations` | Retrieve AI conversation transcripts |
| POST | `/inventory/new` | Upload new vehicle inventory |
| POST | `/inventory/used` | Upload used vehicle inventory |
| GET | `/inventory/vehicle/{vin}` | Look up a vehicle by VIN |

## Key resources

- **ailm** — AI lead management - contact creation and engagement
- **conversations** — Read-back of AI assistant transcripts
- **inventory** — New and used vehicle feeds with VIN-keyed lookup

## Why Jentic

- **Setup:** Wiring the DealerAI API by hand means learning its HTTP Basic auth, building the Authorization header yourself, and mapping its /ailm engagement and /inventory endpoints. Through Jentic you install once, import the DealerAI API from the API Directory, store the Basic credentials once, and your agent calls it.
- **Permission scoping:** DealerAI puts the vehicle id in the URL path (`/inventory/vehicle/{vin}`), so a rule can pin your agent to a single vehicle for reads. You choose the operations it may call, so contact engagement or inventory posting are included only if you add them.
- **Credential handling:** Your DealerAI username and password are stored once, encrypted, by your own Jentic One instance and used to build the Authorization header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'engage a DealerAI contact' or 'upload used vehicle inventory', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without learning DealerAI's /ailm and /inventory path conventions.

## Related APIs

- **Edmunds API** — Vehicle reference data, pricing, and specifications for automotive workflows.
- **Salesforce API** — General-purpose CRM widely used in automotive groups for centralised lead management.
- **HubSpot CRM Contacts** — Marketing-led CRM that pairs with dealership tools for nurture sequences.

## FAQ

### What authentication does the DealerAI API use?

DealerAI uses HTTP Basic authentication on every endpoint. Through Jentic the username and password are held in the encrypted vault and applied at execution time, so the raw credentials never enter the agent's context.

### Can I create a lead in DealerAI without triggering an AI message?

Yes. POST `/ailm/contact` creates or updates the contact silently. Use `/ailm/engage` as a separate call when you want the AI assistant to actually reach out, which lets you batch-import leads first and engage selectively.

### How do I look up a specific vehicle in DealerAI?

Call GET `/inventory/vehicle/{vin}` with the 17-character VIN. The response confirms whether the vehicle is in the current dealership feed and returns its stored attributes. Use this before pointing a customer at a specific car.

### What are the rate limits for the DealerAI API?

The OpenAPI spec does not document explicit rate limits. Treat the inventory POSTs as bulk operations - push a full feed once per scheduling window rather than per-vehicle to keep request volume reasonable.

### How do I push a lead and trigger AI follow-up through Jentic?

Run pip install jentic, search for 'engage a DealerAI contact', and Jentic returns the `/ailm/engage` operation with its input schema. Load it, supply the contact identifier and engagement payload, and execute. Pair with `/ailm/contact` first if the lead is new.

### Does DealerAI handle finance, F&I, or service appointment booking?

No. The v1 API is scoped to lead engagement, conversation logs, and inventory feeds. There are no endpoints for finance applications, deal jackets, or service scheduling - pair with a DMS or service-scheduling API for those.

### Can I limit what my agent is allowed to do with the DealerAI API?

Yes. Because you run Jentic One yourself, your own rules decide which DealerAI operations the agent may call and which credentials it may use, so you can allow read-only conversation and VIN lookups while withholding writes like POST `/ailm/contact`, POST `/ailm/engage`, or the inventory feed uploads. Since DealerAI puts the vehicle identifier in the URL path at GET `/inventory/vehicle/{vin}`, a rule can pin the agent to a single vehicle for reads. Contact engagement or inventory posting are included only if you add them.