Send your customer a notice when the car they wanted arrives

Car dealershipsOnly in car-dealership workspaces.

A customer asks "let me know when a Mazda CX-30, 2021 or newer, comes in under 18 million". That promise is called a Búsqueda, a record of what the customer wants. It stays open until a car fulfils it, it's cancelled, or it expires. This recipe explains how it fulfils itself, and what you can read about it from your integration today.

How it fulfils itself, with no call from you

A Búsqueda gets created from the conversation with the AI agent, or by hand in the app. It stays open until a car fulfils it, either exactly or with a difference inside the workspace's tolerance. It also closes if it's cancelled, or if it expires.

A car fulfils it through two paths, and both run without anyone calling anything:

• The moment it happens: creating a vehicle, one becoming available again, or a price cut fires the same event. That event grades every open Búsqueda against that car.
• Once a day: a check compares every open Búsqueda against current stock.

The customer gets the automatic notice, over WhatsApp or whatever channel they preferred, at most one notice per Búsqueda a day. The salesperson finds out after, never before. A bell and a WhatsApp of their own say which car, which customer, and whether the match was exact or partial.

The one endpoint: who is waiting for this car

Camila asked for a Toyota Yaris, 2020 or newer, up to 11,500,000. This recipe's car costs 11,990,000: it goes over her cap, but only just.

curl "https://api.vitrinadev.com/api/v1/vehicles/26a00eb8-62ce-4a02-a9a7-72204ed8a392/busquedas" \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": [
    {
      "subscription_id": "b4add9ff-95df-4a08-9c7c-b817bc4c2474",
      "contact": { "name": "Camila Rojas", "phone": "+56945678123" },
      "lead_id": "2fa9c593-1200-4e2d-88d6-0bf8e637261f",
      "status": "open",
      "trigger_key": "vehicle_in_stock",
      "criteria": { "make": "Toyota", "model": "Yaris", "year_min": 2020, "max_price": 11500000 },
      "sought_label": "Toyota Yaris · 2020 en adelante",
      "days_left": 90,
      "notice_count": 0,
      "verdict": "calza_parcial",
      "differences": [
        {
          "bound": "budget",
          "stated": 11500000,
          "actual": 11990000,
          "over": 490000,
          "text": "Está $490.000 sobre el presupuesto de $11.500.000"
        }
      ],
      "already_notified": false
    }
  ],
  "meta": { "total": 1 }
}

The record doesn't carry a plain yes or no. It carries differences, with how much it went over and a phrase already written in text, ready for your screen. Now Rodrigo asks for the same car, with a higher cap, and subscribes:

{
  "data": [
    {
      "subscription_id": "03a1ef74-8150-45b0-9059-54678dd25a65",
      "contact": { "name": "Rodrigo Paredes", "phone": "+56978451236" },
      "lead_id": "ce5fdcc1-ae78-468f-a7aa-5b9b587c38ca",
      "status": "open",
      "trigger_key": "vehicle_in_stock",
      "criteria": { "make": "Toyota", "model": "Yaris", "year_min": 2020, "max_price": 13000000 },
      "sought_label": "Toyota Yaris · 2020 en adelante",
      "days_left": 90,
      "notice_count": 0,
      "verdict": "calza",
      "differences": [],
      "already_notified": false
    },
    {
      "subscription_id": "b4add9ff-95df-4a08-9c7c-b817bc4c2474",
      "contact": { "name": "Camila Rojas", "phone": "+56945678123" },
      "status": "open",
      "verdict": "calza_parcial",
      "differences": [{ "bound": "budget", "over": 490000 }],
      "already_notified": false
    }
  ],
  "meta": { "total": 2 }
}

The same call now answers with both. Rodrigo's cap is enough, so differences comes back empty for him. Camila's stays the same. Every call re-grades every open Búsqueda against the car, so one created after the fact still shows up here.

Two things about this endpoint that aren't obvious:

• The scope is followups:read, not marketplace:read. What it returns is the demand recorded in the CRM, not stock.
• The name and phone, inside contact, also need contacts:read. Without that scope, the record still arrives, just without those two fields.

When it fails

A workspace on another vertical gets 403 on this endpoint even with the right scopes: Vehicles, and everything under /vehicles, is only available to automotive workspaces.

In the app: this shows in the vehicle pipeline, Solicitudes view. That's where a customer's ask for a car that isn't on the lot gets recorded. Full guide at Automotora manual → Pipelines and reconditioning.

Sometimes the automatic notice isn't enough, or you want to close the loop yourself for someone who came back with a partial match. For that, see Reopen a cold conversation with a template, without Meta blocking you.